ÉÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ» º º º Netware C Library º º º º Version 2.3 º º º º Reference Manual º º º º Copyright (c) Adrian M. Cunnelly 1992-1994 º º º º Internet: adrian@amcsoft.demon.co.uk º º Compuserve: 100031,222 º º º ÈÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍͼ Netware C Library Contents-1 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 1. Introduction.........................................1-1 1.1 General Information............................1-1 1.2 Registration Information.......................1-1 1.3 Disclaimer.....................................1-1 1.4 Future Enhancements............................1-1 1.5 Change History.................................1-2 1.6 Function Summary...............................1-3 1.7 Netware Data Types.............................1-6 2. Bindery Services.....................................2-1 2.1 Bindery Objects................................2-1 2.1.1 Object Type .............................2-1 2.1.2 Object Name..............................2-2 2.1.3 Object Flag..............................2-2 2.1.4 Object Security..........................2-2 2.1.5 Properties Flag..........................2-2 2.2 Properties and their values....................2-2 2.2.1 Property Name............................2-2 2.2.2 Property Flag............................2-3 2.2.3 Property Security........................2-3 2.2.4 Property Values Flag.....................2-3 2.3 Bindery Functions..............................2-3 2.3.1 AddBinderyObjectToSet...................2-3 2.3.2 ChangeBinderyObjectPassword.............2-4 2.3.3 ChangeBinderyObjectSecurity.............2-4 2.3.4 ChangePropertySecurity..................2-4 2.3.5 CloseBindery............................2-4 2.3.6 CreateBinderyObject.....................2-5 2.3.7 CreateProperty..........................2-5 2.3.8 DeleteBinderyObjectFromSet..............2-5 2.3.9 DeleteBinderyObject.....................2-6 2.3.10 DeleteProperty..........................2-6 2.3.11 GetBinderyAccessLevel...................2-6 2.3.12 GetBinderyObjectID......................2-6 2.3.13 GetBinderyObjectName....................2-7 2.3.14 IsBinderyObjectInSet....................2-7 2.3.15 OpenBindery.............................2-7 2.3.16 ReadPropertyValue.......................2-8 2.3.17 RenameBinderyObject.....................2-8 2.3.18 ScanBinderyObject.......................2-9 2.3.19 ScanProperty............................2-9 2.3.20 VerifyBinderyObjectPassword.............2-10 2.3.21 VerifyObjectPasswordEncrypted...........2-10 2.3.22 WritePropertyValue......................2-11 3. File Server Environment Services....................3-1 3.1 File Server Environment Functions..............3-1 Netware C Library Contents-2 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 3.1.1 CheckConsolePrivileges..................3-1 3.1.2 ClearConnectionNumber...................3-1 3.1.3 DisableFileServerLogin..................3-1 3.1.4 DisableTransactionTracking..............3-1 3.1.5 DownFileServer..........................3-2 3.1.6 EnableFileServerLogin...................3-2 3.1.7 EnableTransactionTracking...............3-2 3.1.8 EncryptPassword.........................3-2 3.1.9 GetBinderyObjectDiskSpaceLeft...........3-3 3.1.10 GetConnectionsOpenFiles.................3-3 3.1.11 GetConnectionsUsageStatistics...........3-5 3.1.12 GetDiskCacheStatistics..................3-5 3.1.13 GetDiskUtilisation......................3-5 3.1.14 GetFileServerDateTime...................3-6 3.1.15 GetFileServerInformation................3-6 3.1.16 GetFileServerLoginStatus................3-6 3.1.17 GetNetworkSerialNumber..................3-7 3.1.18 GetPathFromDirectoryEntry...............3-7 3.1.19 GetPhysicalDiskStatistics...............3-7 3.1.20 GetSemaphoreInformation.................3-8 3.1.21 SendConsoleBroadcast....................3-8 4. Connection Services.................................4-1 4.1 Connection Functions...........................4-1 4.1.1 AttachToFileServer......................4-1 4.1.2 DetachFromFileServer....................4-1 4.1.3 EnterLoginArea..........................4-1 4.1.4 GetConnectionInformation................4-2 4.1.5 GetConnectionNumber.....................4-2 4.1.6 GetInternetAddress......................4-2 4.1.7 GetObjectConnectionNumbers..............4-3 4.1.8 GetStationAddress.......................4-3 4.1.9 LoginObjectEncrypted....................4-3 4.1.10 LoginToFileServer.......................4-4 4.1.11 LogoutFromFileServer....................4-4 4.1.12 Logout..................................4-4 5. Workstation Services................................5-1 5.1 Multiple Servers...............................5-1 5.2 Workstation Functions..........................5-1 5.2.1 EndOfJob................................5-1 5.2.2 GetConnectionIDTable....................5-1 5.2.3 GetDefaultConnectionID..................5-2 5.2.4 GetDriveConnectionID....................5-2 5.2.5 GetDriveFlagTable.......................5-2 5.2.6 GetDriveHandleTable.....................5-2 5.2.7 GetFileServerTable......................5-3 5.2.8 GetNetwareShellVersion..................5-3 5.2.9 GetNumberOfLocalDrives..................5-3 5.2.10 GetPreferredConnectionID................5-3 5.2.11 GetPrimaryConnectionID..................5-4 Netware C Library Contents-3 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 5.2.12 GetServerConnectionID...................5-4 5.2.13 IsShellLoaded...........................5-4 5.2.14 SetEndofJobStatus.......................5-4 5.2.15 SetNWErrorMode..........................5-5 5.2.16 SetPreferredConnectionID................5-5 5.2.17 SetPrimaryConnectionID..................5-5 6. Message Services....................................6-1 6.1 Message Functions..............................6-1 6.1.1 BroadcastToConsole......................6-1 6.1.2 CheckPipeStatus.........................6-1 6.1.3 CloseMessagePipe........................6-2 6.1.4 GetBroadcastMessage.....................6-2 6.1.5 GetBroadcastMode........................6-3 6.1.6 GetPersonalMessage......................6-3 6.1.7 LogNetworkMessage.......................6-4 6.1.8 OpenMessagePipe.........................6-4 6.1.9 SendBroadcastMessage....................6-4 6.1.10 SendPersonalMessage.....................6-5 6.1.11 SetBroadcastMode........................6-6 7. File Services.......................................7-1 7.1 Directory Handles..............................7-1 7.2 Search Attributes..............................7-1 7.3 File Attributes................................7-1 7.4 Extended File Attributes.......................7-2 7.5 File Functions.................................7-2 7.5.1 EraseFiles..............................7-2 7.5.2 PurgeAllErasedFiles.....................7-3 7.5.3 PurgeErasedFiles........................7-3 7.5.4 ScanFileInformation.....................7-3 8. Directory Services..................................8-1 8.1 Directory Handle Table.........................8-1 8.2 Drive Handle Table.............................8-1 8.3 Drive Flag Table...............................8-1 8.4 Drive Connection ID Table......................8-2 8.5 Trustee Rights Mask............................8-2 8.6 Directory Functions............................8-2 8.6.1 AddTrusteeToDirectory...................8-2 8.6.2 AllocPermanentDirectoryHandle...........8-3 8.6.3 AllocTemporaryDirectoryHandle...........8-3 8.6.4 CreateDirectory.........................8-4 8.6.5 DeallocateDirectoryHandle...............8-4 8.6.6 DeleteDirectory.........................8-5 8.6.7 DeleteFakeRoot..........................8-5 8.6.8 DeleteTrusteeFromDirectory..............8-5 8.6.9 GetCurrentDirectory.....................8-6 8.6.10 GetDirectoryHandle......................8-6 8.6.11 GetDirectoryPath........................8-6 Netware C Library Contents-4 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 8.6.12 GetEffectiveDirectoryRights.............8-7 8.6.13 GetVolumeInformation....................8-7 8.6.14 GetVolumeInfoWithHandle.................8-8 8.6.15 GetVolumeInfoWithNumber.................8-8 8.6.16 GetVolumeName...........................8-9 8.6.17 GetVolumeNumber.........................8-9 8.6.18 MapFakeRoot.............................8-9 8.6.19 ModifyMaximumRightsMask.................8-10 8.6.20 RenameDirectory.........................8-10 8.6.21 RestoreDirectoryHandle..................8-10 8.6.22 SaveDirectoryHandle.....................8-11 8.6.23 ScanBinderyObjectTrusteePaths...........8-11 8.6.24 ScanDirectoryForTrustees................8-11 8.6.25 ScanDirectoryInformation................8-12 8.6.26 SetDirectoryHandle......................8-13 9. Print Services......................................9-1 9.1 Print Functions................................9-1 9.1.1 CancelLPTCapture........................9-1 9.1.2 CancelSpecificLPTCapture................9-1 9.1.3 EndLPTCapture...........................9-1 9.1.4 EndSpecificLPTCapture...................9-1 9.1.5 FlushLPTCapture.........................9-2 9.1.6 FlushSpecificLPTCapture.................9-2 9.1.7 GetBannerUserName.......................9-2 9.1.8 GetLPTCaptureStatus.....................9-2 9.1.9 GetDefaultLocalPrinter..................9-2 9.1.10 GetDefaultCaptureFlags..................9-3 9.1.11 GetPrinterStatus........................9-3 9.1.12 GetSpecificCaptureFlags.................9-3 9.1.13 SetBannerUserName.......................9-4 9.1.14 SetCapturePrintQueue....................9-4 9.1.15 SetDefaultLocalPrinter..................9-4 9.1.16 SetDefaultCaptureFlags..................9-4 9.1.17 SetSpecificCaptureFlags.................9-5 9.1.18 SpecifyCaptureFile......................9-5 9.1.19 StartLPTCapture.........................9-5 9.1.20 StartSpecificLPTCapture.................9-5 10. Synchronisation Services...........................10-1 10.1 Semaphores....................................10-1 10.2 Synchronisation Functions.....................10-2 10.2.1 CloseSemaphore..........................10-2 10.2.2 ExamineSemaphore........................10-2 10.2.3 OpenSemaphore...........................10-2 10.2.4 SignalSemaphore.........................10-3 10.2.5 WaitOnSemaphore.........................10-3 11. Communication Services.............................11-1 11.1 IPX Protocol..................................11-1 Netware C Library Contents-5 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 11.1.1 IPX Packet Structure....................11-1 11.2 SPX Protocol..................................11-2 11.2.1 SPX Packet Structure....................11-2 11.3 Event Control Block (ECB).....................11-4 11.3.1 ECB Structure...........................11-4 11.4 IPX Functions.................................11-7 11.4.1 IPXCancelEvent..........................11-7 11.4.2 IPXCloseSocket..........................11-7 11.4.3 IPXDisconnectFromTarget.................11-7 11.4.4 IPXGetInternetworkAddress...............11-8 11.4.5 IPXGetIntervalMarker....................11-8 11.4.6 IPXGetLocalTarget.......................11-8 11.4.7 IPXInitialise...........................11-8 11.4.8 IPXListenForPacket......................11-9 11.4.9 IPXOpenSocket...........................11-9 11.4.10 IPXRelinquishControl....................11-9 11.4.11 IPXScheduleIPXEvent.....................11-10 11.4.12 IPXSendPacket...........................11-10 11.5 SPX Functions..................................11-11 11.5.1 SPXAbortConnection......................11-11 11.5.2 SPXEstablishConnection..................11-11 11.5.3 SPXGetConnectionStatus..................11-12 11.5.4 SPXInitialise...........................11-12 11.5.5 SPXListenForConnection..................11-12 11.5.6 SPXListenForSequencedPacket.............11-13 11.5.7 SPXSendSequencedPacket..................11-14 11.5.8 SPXTerminateConnection..................11-14 Appendix I Netware Result Codes......................A1-1 Appendix II Function List.............................A2-1 Appendix III Data Structures...........................A3-1 A3.1 CONNECTION_ID_TABLE...........................A3-1 A3.2 DISK_CACHE_STATISTICS.........................A3-3 A3.3 FILE_SERVER_INFO..............................A3-5 A3.4 PHYSICAL_DISK_STATISTICS......................A3-6 A3.5 PRINT_CONTROL_DATA............................A3-8 A3.6 VOLUME_STATISTICS.............................A3-10 A3.7 SPX_CONNECTION_STATUS.........................A3-11 Appendix IV Order Form................................A4-1 Netware C Library Chapter One - Introduction Page: 1-1 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 1. Introduction 1.1 General Information This document and the associated C libraries provide the network programmer with a whole host of functions for accessing Novell Netware Services. Only the small memory model libraries for Microsoft C, Turbo C and Borland C++ are provided, but medium and large memory models are provided with registration. The source code is also available, see registration below, enabling libraries for other compilers to be produced. The libraries were produced using Microsoft C v6.0, Turbo C v2.0 and Borland C++ v2.0. All the functions have been tested with Novell Advanced Netware 286 v2.15, and some have been tested on Netware 3.11. 1.2 Registration Information Registration provides the following :- þ Latest version of the libraries which will include small, medium and large memory models for Microsoft C, Turbo C and Borland C++. þ Royalty-free use of all library functions. þ Unlimited technical support. þ Low-cost upgrades. A disk containing the full source code is also available for a small fee, see the file "order.txt" for registration details and prices, a copy of this is provided in Appendix IV of this manual. 1.3 Disclaimer The author, Adrian Cunnelly, claims no responsibility for any damages caused by the use or misuse of this product. This product is distributed "as is" with no warranty expressed or implied. The author will not be responsible for any losses incurred, either directly or indirectly, by the use of this product. Use this product entirely at your own risk. The author reserves the right to make modifications at any time. Prices are subject to change without notice. 1.4 Future Enhancements Future versions of this library will contain Accounting, TTS, VAP, Queue and IPX Diagnostic Services along with additional File and Synchronization Services. All registered users will be automatically informed of all updates. Which will be available for the price of a disk + postage. Netware C Library Chapter One - Introduction Page: 1-2 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 1.5 Change History Changes from the previous release: þ New functions "EncryptPassword" - File Server Services "GetNetworkSerialNumber" - File Server Services "LoginObjectEncrypted" - Connection Services "VerifyObjectPasswordEncrypted" - Connection Services þ Documentation for "ScanBinderyObject" has been amended. þ Corrected problem in IPXGetLocalTarget. The complete history of changes can be found in the file "History.txt". Netware C Library Chapter One - Introduction Page: 1-3 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 1.6 Function Summary The functions in this library provide the following services: Message Services: BroadcastToConsole LogNetworkMessage CheckPipeStatus OpenMessagePipe CloseMessagePipe SendBroadcastMessage GetBroadcastMessage SendPersonalMessage GetBroadcastMode SetBroadcastMode GetPersonalMessage Connection Services: AttachToFileServer GetObjectConnectionNumbers DetachFromFileServer GetStationAddress EnterLoginArea LoginObjectEncrypted GetConnectionInformation LoginToFileServer GetConnectionNumber LogoutFromFileServer GetInternetAddress Logout VerifyObjectPasswordEncrypted Directory Services: AddTrusteeToDirectory GetVolumeInfoWithHandle AllocPermanentDirectoryHandle GetVolumeInfoWithNumber AllocTemporaryDirectoryHandle GetVolumeName CreateDirectory GetVolumeNumber DeallocateDirectoryHandle MapFakeRoot DeleteDirectory ModifyMaximumRightsMask DeleteFakeRoot RenameDirectory DeleteTrusteeFromDirectory RestoreDirectoryHandle GetCurrentDirectory SaveDirectoryHandle GetDirectoryHandle ScanBinderyObjectTrusteePaths GetDirectoryPath ScanDirectoryForTrustees GetEffectiveDirectoryRights ScanDirectoryInformation GetVolumeInformation SetDirectoryHandle File Server Environment Services: CheckConsolePrivileges GetDiskCacheStatistics ClearConnectionNumber GetDiskUtilisation DisableFileServerLogin GetFileServerDateTime DisableTransactionTracking GetFileServerInformation DownFileServer GetFileServerLoginStatus EnableFileServerLogin GetNetworkSerialNumber EnableTransactionTracking GetPathFromDirectoryEntry EncryptPassword GetPhysicalDiskStatistics GetBinderyObjectDiskSpaceLeft GetSemaphoreInformation GetConnectionsOpenFiles SendConsoleBroadcast GetConnectionsUsageStatistics Netware C Library Chapter One - Introduction Page: 1-4 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Bindery Services: AddBinderyObjectToSet GetBinderyObjectID ChangeBinderyObjectPassword GetBinderyObjectName ChangeBinderyObjectSecurity IsBinderyObjectInSet ChangePropertySecurity OpenBindery CloseBindery ReadPropertyValue CreateBinderyObject RenameBinderyObject CreateProperty ScanBinderyObject DeleteBinderyObjectFromSet ScanProperty DeleteBinderyObject VerifyBinderyObjectPassword DeleteProperty WritePropertyValue GetBinderyAccessLevel Workstation Services: EndOfJob GetPreferredConnectionID GetConnectionIDTable GetPrimaryConnectionID GetDefaultConnectionID GetServerConnectionID GetDriveConnectionID IsShellLoaded GetDriveFlagTable SetEndofJobStatus GetDriveHandleTable SetNWErrorMode GetFileServerTable SetPreferredConnectionID GetNetwareShellVersion SetPrimaryConnectionID GetNumberOfLocalDrives Print Services: CancelLPTCapture GetPrinterStatus CancelSpecificLPTCapture GetSpecificCaptureFlags EndLPTCapture SetBannerUserName EndSpecificLPTCapture SetCapturePrintQueue FlushLPTCapture SetDefaultLocalPrinter FlushSpecificLPTCapture SetDefaultCaptureFlags GetBannerUserName SetSpecificCaptureFlags GetLPTCaptureStatus SpecifyCaptureFile GetDefaultLocalPrinter StartLPTCapture GetDefaultCaptureFlags StartSpecificLPTCapture File Services: EraseFiles PurgeErasedFiles PurgeAllErasedFiles ScanFileInformation Synchronisation Services: CloseSemaphore SignalSemaphore ExamineSemaphore WaitOnSemaphore OpenSemaphore Netware C Library Chapter One - Introduction Page: 1-5 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Communication Services: IPXCancelEvent IPXInitialise IPXCloseSocket IPXListenForPacket IPXDisconnectFromTarget IPXOpenSocket IPXGetInternetworkAddress IPXRelinquishControl IPXGetIntervalMarker IPXScheduleIPXEvent IPXGetLocalTarget IPXSendPacket SPXAbortConnection SPXListenForConnection SPXEstablishConnection SPXListenForSequencedPacket SPXGetConnectionStatus SPXSendSequencedPacket SPXInitialise SPXTerminateConnection Netware C Library Chapter One - Introduction Page: 1-6 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 1.7 Netware Data Types Netware numeric items are different from the native representation internal to the PC. Instead of integers being in low-high format Netware expects them to be in high-low format. This means that the bytes of int and long values will have to be swapped round. The following structures are declared in the header file "Netware.h": typedef unsigned long dword; /* four bytes */ typedef unsigned int word; /* two bytes */ typedef unsigned char byte; /* single byte */ typedef struct { byte hi_byte; byte lo_byte; } nw_int; typedef struct { byte hihi_byte; byte hilo_byte; byte lohi_byte; byte lolo_byte; } nw_long; And the following functions are provided to convert between Netware internal format and native PC format: PC int -> Netware int: void NWintconvert(int in,nw_int *convert); PC long -> Netware long: void NWlongconvert(unsigned long in,nw_long *convert); Netware int -> PC int: int convertNWint(nw_int in); Netware long -> PC long: long convertNWlong(nw_long *in); Netware C Library Chapter Two - Bindery Services Page: 2-1 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 2. Bindery Services The bindery is basically a database, maintained by the Netware file server, of the resources and users available on the network. It consists of objects and properties. An object can be a user,group or any other entity on the network that has been given a name. Each object can have many properties associated with it, and each property may have an associated value. ÚÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ Object ³ ÀÄÄÄÄÄÂÄÄÄÄÄÄÙ ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ÚÄÄÄÄÄÄÁÄÄÄÄÄÄ¿ ÚÄÄÄÄÄÄÁÄÄÄÄÄÄ¿ ÚÄÄÄÄÄÄÁÄÄÄÄÄÄ¿ ³ Property ³ ³ Property ³ ³ Property ³ ÀÄÄÄÄÄÄÂÄÄÄÄÄÄÙ ÀÄÄÄÄÄÄÂÄÄÄÄÄÄÙ ÀÄÄÄÄÄÄÂÄÄÄÄÄÄÙ ÚÄÄÄÄÄÄÁÄÄÄÄÄÄ¿ ÚÄÄÄÄÄÄÁÄÄÄÄÄÄ¿ ÚÄÄÄÄÄÄÁÄÄÄÄÄÄ¿ ³ Prop Value ³ ³ Prop Value ³ ³ Prop Value ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÙ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÙ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÙ 2.1 Bindery Objects Each bindery object consists of: object ID, object type, object name, object flag, object security, and properties flag. The object ID is a 4-byte unique identifier assigned by Netware when the object is created. The object type and object name uniquely identify the object. The object flag indicates whether the object is dynamic or static. The object security determines whether other objects can access it. The properties flag indicates whether the object has any properties associated with it. 2.1.1 Object Type The following object types are currently recognised by Netware: Description Object Type #define in Netware.h Unknown 0x0000 UNKNOWN User 0x0001 USER User Group 0x0002 USER_GROUP Print Queue 0x0003 PRINT_Q File Server 0x0004 FILE_SERVER Job Server 0x0005 JOB_SERVER Gateway 0x0006 GATEWAY Print Server 0x0007 PRN_SERVER Archive Queue 0x0008 ARCHIVE_Q Archive Server 0x0009 ARC_SERVER Job Queue 0x000a JOB_Q Administration 0x000b ADMIN Remote Bridge Server 0x0026 REM_BRIDGE Advertising Print Server 0x0047 ADV_PRN_SERVER Reserved up to 0x8000 Wild 0xffff (-1) WILDCARD Netware C Library Chapter Two - Bindery Services Page: 2-2 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 2.1.2 Object Name The object name contains a 48-byte null terminated string. The name can be 1 - 47 characters long and must contain only printable characters, it cannot include spaces or the following characters: slash (/), backslash (\), colon (:), semicolon (;), comma (,), asterisk (*) and question mark (?). 2.1.3 Object Flag The object flag specifies whether the object is Static (0x00) or Dynamic (0x01). A static object is permanent until it is specifically deleted, but a dynamic object will disappear when the file server is rebooted. 2.1.4 Object Security The object security specifies who has access rights to the object, it consists of 1 byte where the low-order nibble (bottom 4 bits) define the read access and the high-order nibble (top 4 bits) define the write access. The following are defined for each nibble: Binary Access Description 0 0 0 0 Anyone Access allowed to all users 0 0 0 1 Logged Access to all logged in users 0 0 1 0 Object Access only to users who have logged in with this object name,type and password 0 0 1 1 Supervisor Access only to supervisor users 0 1 0 0 Netware Access only allowed by Netware itself 2.1.5 Properties flag The properties flag is an indicator which is set if there are any properties associated with this object. 2.2 Properties and their Values Properties are either Item Properties or Set Properties. An item property has associated with it a 128 byte value, whereas a set property has associated with it a list of 1 to 32 object IDs contained in a 128 byte segment. Each property consists of: property name, property flags, property security and property values flag. 2.2.1 Property Name The property name can be 1 to 15 characters long of which the following are currently defined by Netware: LOGIN_CONTROL Item ACCOUNT_SERVERS Set ACCOUNT_BALANCE Item SECURITY_EQUALS Set PASSWORD Item GROUP_MEMBERS Set NET_ADDRESS Item GROUPS_I'M_IN Set IDENTIFICATION Item OPERATORS Set Netware C Library Chapter Two - Bindery Services Page: 2-3 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 2.2.2 Property Flag The property flags is a 1 byte field, where only 2 bits are defined: Bits 7 6 5 4 3 2 1 0 - - - - - - - 0 The property is static - - - - - - - 1 The property is dynamic - - - - - - 0 - The property is an item - - - - - - 1 - The property is a set 2.2.3 Property Security The property security specifies who has access rights to the property, it consists of 1 byte where the low-order nibble (bottom 4 bits) defines who can scan for and find the property and the high-order nibble (top 4 bits) defines who can add values to the property. The following are defined for each nibble: Binary Access Description 0 0 0 0 Anyone Access allowed to all users 0 0 0 1 Logged Access to all logged in users 0 0 1 0 Object Access only to users who have logged in with this object name,type and password 0 0 1 1 Supervisor Access only to supervisor users 0 1 0 0 Netware Access only allowed by Netware itself 2.2.4 Property Values Flag The property values flag is an indicator which is set if there are any values associated with this property. 2.3 Bindery Functions 2.3.1 AddBinderyObjectToSet Adds a bindery object to a set property. int AddBinderyObjectToSet(int objectType,char *objectName, char *propertyName,int memberType, char *memberName); Input: objectType: Bindery object type of property owner objectName: 48-byte null terminated Object Name of property owner propertyName: 16-byte null terminated Property Name memberType: Bindery object type of object to add to set memberName: 48-byte null terminated Object name of object to add to set Returns: Result code (see Appendix I) Netware C Library Chapter Two - Bindery Services Page: 2-4 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 2.3.2 ChangeBinderyObjectPassword Changes the password of a bindery object. int ChangeBinderyObjectPassword(int objectType,char *objectName, char *oldPass,char *newPass); Input: objectType: Bindery object type objectName: 48-byte null terminated Object Name oldPass: 128-byte null terminated old password newPass: 128-byte null terminated new password Returns: Result code (see Appendix I) 2.3.3 ChangeBinderyObjectSecurity Allows the supervisor to change the security of a bindery object. int ChangeBinderyObjectSecurity(byte newSecurity,int objectType, char *objectName); Input: newSecurity: The new security setting for this object objectType: Bindery object type objectName: 48-byte null terminated Object Name Returns: Result code (see Appendix I) 2.3.4 ChangePropertySecurity Changes the security of a bindery objects property. int ChangePropertySecurity(int objectType,char *objectName, byte newPropSecurity,char *propName); Input: objectType: Bindery object type objectName: 48-byte null terminated Object Name newPropSecurity: The new property security propName: 16-byte null terminated Property name Returns: Result code (see Appendix I) 2.3.5 CloseBindery (Supervisor) Allows the supervisor to close the bindery, it closes both bindery files (NET$BIND.SYS & NET$BVAL.SYS). Whilst the bindery is closed no other bindery calls can be serviced, so the time spent with the bindery closed should be kept to a minimum. int CloseBindery(void); Returns: Result code (see Appendix I) Netware C Library Chapter Two - Bindery Services Page: 2-5 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 2.3.6 CreateBinderyObject (Supervisor) Allows the supervisor to create a bindery object. int CreateBinderyObject(byte flag,byte security,int objectType, char *objectName); Input: flag: Specifies whether static (0x00) or dynamic (0x01) security: Security setting for this object objectType: Bindery object type objectName: 48-byte null terminated Object name Returns: Result code (see Appendix I) 2.3.7 CreateProperty Adds a property to a bindery object. int CreateProperty(int objectType,char *objectName, byte propFlags,byte propSecurity, char *propName); Input: objectType: Bindery object type objectName: 48-byte null terminated Object name propFlags: Property flags (static/dynamic & item/set) propSecurity: Security setting for this property propName: 16-byte null terminated Property name Returns: Result code (see Appendix I) 2.3.8 DeleteBinderyObjectFromSet Deletes a bindery object from a set property. int DeleteBinderyObjectFromSet(int objectType,char *objectName, char *propertyName,int memberType, char *memberName); Input: objectType: Bindery object type of property owner objectName: 48-byte null terminated Object name of property owner propertyName: 16-byte null terminated Set Property name memberType: Bindery object type of object to remove from set memberName: 48-byte null terminated Object name of object to remove from set Returns: Result code (see Appendix I) Netware C Library Chapter Two - Bindery Services Page: 2-6 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 2.3.9 DeleteBinderyObject (Supervisor) Allows the supervisor to delete a bindery object. int DeleteBinderyObject(int objectType,char *objectName); Input: objectType: Bindery object type objectName: 48-byte null terminated Object name Returns: Result code (see Appendix I) 2.3.10 DeleteProperty Deletes a property from a bindery object. int DeleteProperty(int objectType,char *objectName, char *propName); Input: objectType: Bindery object type objectName: 48-byte null terminated Object name propName: 16-byte null terminated Property name Returns: Result code (see Appendix I) 2.3.11 GetBinderyAccessLevel Returns the requesting workstation's access level to the server's bindery. int GetBinderyAccessLevel(long *objectID,byte *accessLevel); Output: objectID: Returns Bindery object ID of logged in user accessLevel: Returns Bindery access level of logged in user. See Object Security in the definition of Bindery Objects. Returns: Result code (see Appendix I) 2.3.12 GetBinderyObjectID Returns a bindery object's identification number. int GetBinderyObjectID(word objectType,char *objectName, long *objectID); Input: objectType: Bindery object type objectName: 48-byte null terminated Object name Output: objectID: Returned object ID number of specified object. Returns: Result code (see Appendix I) Netware C Library Chapter Two - Bindery Services Page: 2-7 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 2.3.13 GetBinderyObjectName Returns the type and name of the specified object. int GetBinderyObjectName(long objectID,word *objectType, char *objectName); Input: objectID: Bindery object identification number Output: objectType: Bindery object type objectName: 48-byte null terminated Bindery object name Returns: Result code (see Appendix I) 2.3.14 IsBinderyObjectInSet Determines if a bindery object is a member of the specified set property. int IsBinderyObjectInSet(int objectType,char *objectName, char *propertyName,int memberType, char *memberName); Input: objectType: Bindery object type of property owner objectName: 48-byte null terminated Object Name of property owner propertyName: 16-byte null terminated Property Name memberType: Bindery object type of object to check memberName: 48-byte null terminated Object name of object to check Returns: Result code (see Appendix I) 2.3.15 OpenBindery (Supervisor) Allows the supervisor to open the bindery, it opens the two bindery files (NET$BIND.SYS & NET$BVAL.SYS). The bindery files are normally kept open and locked, so this function is only needed following a call to CloseBindery. int OpenBindery(void); Returns: Result code (see Appendix I) Netware C Library Chapter Two - Bindery Services Page: 2-8 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 2.3.16 ReadPropertyValue Returns the value of a bindery objects property. This function must be called repeatedly to return all values associated with a particular property. int ReadPropertyValue(int objectType,char *objectName, char *propertyName,int segment, char *propertyValues,byte *moreSegments, byte *propertyFlag); Input: objectType: Bindery object type objectName: 48-byte null terminated Object name propertyName: 16-byte null terminated Property name segment: The first time this call is made 0x01 should be placed in this field, it should then be increased by 1 for each subsequent call until the call sets the more_segments field to 0x00 or a result code of 0xec (No such segment) is returned. Output: propertyValues: This contains the 128-byte property value. moreSegments: This indicates whether there are any more property values to be read: 0x00 = No more, 0xff = More. propertyFlag: Returns property flag. See definition of Properties. Returns: Result code (see Appendix I) 2.3.17 RenameBinderyObject (Supervisor) Allows the supervisor to rename a bindery object. int RenameBinderyObject(int objectType,char *objectName, char *newObjectName); Input: objectType: Bindery object type objectName: 48-byte null terminated Original bindery object name newObjectName: 48-byte null terminated New object name Returns: Result code (see Appendix I) Netware C Library Chapter Two - Bindery Services Page: 2-9 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 2.3.18 ScanBinderyObject Searches the bindery for the specified object. This can be called iteratively in order to scan the bindery for several objects of a particular type. int ScanBinderyObject(int scanObjectType,char *scanObjectName, long *lastObjectID,int *objectType, char *objectName,byte *objectHasProperties, byte *objectSecurity,byte *objectFlag); Input: scanObjectType: Type of object to scan for. This can be one particular type, e.g. USER 0x0001, or all object types, e.g. WILDCARD 0xffff. scanObjectName: 48-byte null terminated Object name for which the call should scan. The object name can contain wildcard characters. lastObjectID: This should contain 0xffffffff the first time the call is made, otherwise it should contain the previous object id that was returned. Output: lastObjectID: Object ID of object found objectType: Object type of object found objectName: 48-byte null terminated Object name of object found objectHasProperties: 0x00 = No properties associated 0xff = There are some properties objectSecurity: Access security bits. See Object Security in definition of Bindery Objects. objectFlag: 0x00 = Object is Static 0x01 = Object is Dynamic Returns: Result code (see Appendix I) 2.3.19 ScanProperty Searches for an objects property. int ScanProperty(int objectType,char *objectName, char *scanPropertyName,char *propertyName, byte *propertyFlags,byte *propertySecurity, byte *propertyHasValue,byte *moreProperties); Input: objectType: Bindery object type objectName: 48-byte null terminated Object name scanPropertyName: 16-byte null terminated Property name to scan for Netware C Library Chapter Two - Bindery Services Page: 2-10 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Output: propertyName: 16-byte null terminated Name of property found propertyFlags: Returns property flag. See definition of Properties. propertySecurity: Returns property access bits. propertyHasValue: 0x00 = No values associated 0xff = This property has some values moreProperties: 0x00 = No more properties 0xff = Yes there are more properties Returns: Result code (see Appendix I) 2.3.20 VerifyBinderyObjectPassword Verifies that the specified password matches the actual password of the specified bindery object. int VerifyBinderyObjectPassword(int objectType,char *objectName, char *password); Input: objectType: Bindery object type objectName: 48-byte null terminated Object name password: 128-byte null terminated Password to verify Returns: Result code (see Appendix I) 2.3.21 VerifyObjectPasswordEncrypted Verifies that the specified password matches the actual password of the specified bindery object. This function must be used instead of VerifyBinderyObjectPassword if the version of Netware running on the default file server uses encrypted passwords. See the EncryptPassword function in the File Server Environment Services chapter. int VerifyObjectPasswordEncrypted(word objectType,char *objectName, byte *encryptedPassword) Input: objectType: Bindery object type (see Bindery Objects in Bindery Services) objectName: 48-byte null terminated Object name encryptedPassword: 8-byte encrypted password, returned by EncryptPassword. Returns: Result code (see Appendix I) Netware C Library Chapter Two - Bindery Services Page: 2-11 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 2.3.22 WritePropertyValue Writes a value to a property. Property values are stored in 128-byte segments known as value segments. Before creating value segment n, segments 1 through n-1 must be created. This call must not be used to write values to Set Properties, instead use AddBinderyObjectToSet. int WritePropertyValue(int objectType,char *objectName, int segment,byte eraseRemaining, char *propName,byte *value); Input: objectType: Bindery object type objectName: 48-byte null terminated Object name segment: Segment number to write eraseRemaining: This specifies whether any segments that exist after this segment are to be deleted. 0x00 = Erase all following segments 0xff = Do not erase following segments propName: 16-byte null terminated Name of property to amend value: 128-byte value segment to write Returns: Result code (see Appendix I) Netware C Library Chapter Three - File Server Services Page: 3-1 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 3. File Server Environment Services These services allow an application to return information about the file system, transaction tracking system, physical disks, disk channels, volumes, disk caches etc. In fact it provides many of the functions performed by FCONSOLE. Most of the calls in this section require either Operator or Supervisor rights. 3.1 File Server Functions 3.1.1 CheckConsolePrivileges This call returns whether the current logged in user has console operator rights. int CheckConsolePrivileges(void); Returns: 0x00 Successful (has operator rights) 0xc6 No console rights 3.1.2 ClearConnectionNumber (Supervisor) This clears a logical connection from the file server. It closes a connections open files and release any file locks. On a TTS file server it causes a connections transactions to be aborted. int ClearConnectionNumber(int connection); Input: connection: Contains the connection number that the server assigns to a workstation when it attaches to it. Returns: Result code (see Appendix I) 3.1.3 DisableFileServerLogin (Operator) This disables all future logins to the default file server. int DisableFileServerLogin(void); Returns: Result code (see Appendix I) 3.1.4 DisableTransactionTracking (Operator) Disable transaction tracking on the default file server. It has no effect if TTS is not installed. int DisableTransactionTracking(void); Returns: Result code (see Appendix I) Netware C Library Chapter Three - File Server Services Page: 3-2 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 3.1.5 DownFileServer (Supervisor) Close down the file server. int DownFileServer(int forceIt); Input: forceIt: 0x00 = Do not close down if there are any open files 0x01 = Force close down regardless of any open files Returns: Result code (see Appendix I) 3.1.6 EnableFileServerLogin (Operator) Enable logins on the default file server. int EnableFileServerLogin(void); Returns: Result code (see Appendix I) 3.1.7 EnableTransactionTracking (Operator) Enable transaction tracking on the default file server. int EnableTransactionTracking(void); Returns: Result code (see Appendix I) 3.1.8 EncryptPassword Encrypts a bindery objects password. This is only required if the version of Netware running on the default file server uses encrypted passwords. If this function returns a non-zero result code, then encrypted passwords are not supported. int EncryptPassword(long objectID,char *userPassword, char *encryptedPassword) Input: objectID: Bindery object type (see Bindery Objects in Bindery Services) userPassword: 128-byte null terminated password encryptedPassword: 8-byte encrypted password Returns: Result code (see Appendix I) Netware C Library Chapter Three - File Server Services Page: 3-3 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 3.1.9 GetBinderyObjectDiskSpaceLeft Return a bindery objects remaining disk space. int GetBinderyObjectDiskSpaceLeft(long objectID, long *systemElapsedTime,long *unusedDiskBlocks, byte *restrictionsEnforced); Input: objectID: Bindery object identification number, this must be the currently logged in object, unless the logged object has console operator rights. Output: systemElapsedTime: Time that has elapsed since the server was loaded. It is returned in units of approx 1/18th of a second. When this field reaches 0xFFFFFFFF it wraps back to zero. unusedDiskBlocks: This is the number of remaining blocks the bindery object can allocate (1 block=4,096 bytes). The unused disk blocks available to a user do not reflect how much disk space is really available. restrictionsEnforced: 0x00 = Disk resource limit is active 0xff = Disk resource limit is not active Returns: Result code (see Appendix I) 3.1.10 GetConnectionsOpenFiles (Operator) Returns information about files a specific connection has open. This must be called repeatedly to obtain all files that are open. The first call must have "sequence" set to zero, on return if sequence = -1, then there are no more files open. int GetConnectionsOpenFiles(int connection,int *sequence, byte *taskNumber,byte *lockFlag, byte *accessFlag,byte *lockType, byte *nameSpace,byte *volumeNumber, int *parentDirEntry,int *directoryEntry, char *fileName) Input: connection: Logical connection number sequence: On the initial call, this must be zero. On all subsequent calls this must be the value that was returned on the last call. Netware C Library Chapter Three - File Server Services Page: 3-4 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Output: sequence: Next sequence number to use. When this is set to -1, there are no more files open. taskNumber: This is the task number within the workstation that has the file open. lockFlag: Contains bit settings indicating the file's locks. (MSB) Bit 7: Transaction flag set 6: TTS Holding lock 5-4: Not Used 3: Open Normal 2: Logged 1: Open Shareable (LSB) 0: Locked accessFlag: Contains bit settings indicating the connection's access rights to the file :- (MSB) Bit 7: Not Used 6: TTS Holding Open 5: TTS Holding Detach 4: File Detached 3: Deny Write Requests from Other Stations 2: Deny Read Requests from Other Stations 1: Open For Write by this Station (LSB) 0: Open For Read by this Station lockType: A flag indicating the type of lock. 0x00 Not Locked 0xFE Locked by a File Lock 0xFF Locked by Begin Share File Set nameSpace: The name space used by this entry. This is only returned on Netware 3.xx, a value of zero will be returned on Netware 2.xx. volumeNumber: The volume number within the servers Volume Table that holds this file. parentDirEntry: An offset in the servers Directory Entry Table for the volume. Use GetPathFromDirectoryEntry to get the path name this points to. directoryEntry: An offset in the servers Directory Entry Table for the volume. Use GetPathFromDirectoryEntry to get the path name this points to. This will always be the same as parentDirEntry on Netware 2.xx. fileName: 14-byte null terminated string containing the terminal file name. Returns: Result code (see Appendix I) Netware C Library Chapter Three - File Server Services Page: 3-5 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 3.1.11 GetConnectionsUsageStatistics (Operator) Returns a logical connection's usage statistics. Console operator rights are required unless the requesting workstation's connection number is used. int GetConnectionsUsageStatistics(int connection, long *systemElapsedTime,double *bytesRead, double *bytesWritten,long *totalRequestPackets); Input: connection: Logical connection number Output: systemElapsedTime: This is the time, in approximately 1/18ths of a second, that has elapsed since the server was brought up. bytesRead: This is the number of bytes that have been read since the workstation was logged in. bytesWritten: This is the number of bytes that have been written since the workstation was logged in. totalRequestPackets: The number of request packets sent by the workstation to the server since the workstation attached. Returns: Result code (see Appendix I) 3.1.12 GetDiskCacheStatistics (Operator) Return statistics from the default file servers cache software. int GetDiskCacheStatistics(DISK_CACHE_STATISTICS *ReplyBuffer); Output: ReplyBuffer: This contains all cache statistics. It's structure is declared in "Server.h". See Appendix III. Returns: Result code (see Appendix I) 3.1.13 GetDiskUtilisation Returns the disk usage of a bindery object on a volume. int GetDiskUtilisation(long objectID,byte volumeNumber, word *usedDirectories,word *usedFiles, word *usedBlocks); Input: objectID: Bindery object identification number volumeNumber: This identifies the volume in the Volume Table on the file server Netware C Library Chapter Three - File Server Services Page: 3-6 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Output: usedDirectories: The number of directories owned by the bindery object. usedFiles: The number of files created by the bindery object usedBlocks: Space used by "usedFiles" Returns: Result code (see Appendix I) 3.1.14 GetFileServerDateTime Returns the current date and time on the server. void GetFileServerDateTime( int *hours,int *minutes,int *seconds, int *day,int *month,int *year, int *dayOfWeek); Output: hours: Number of Hours (0 to 23) minutes: Number of Minutes (0 to 59) seconds: Number of Seconds (0 to 59) day: Number of day (1 to 31) month: Month number (1 to 12) year: Year dayOfWeek: Day of the Week (0 to 6, 0=Sunday) 3.1.15 GetFileServerInformation Returns information about the default file server. int GetFileServerInformation(FILE_SERVER_INFO *replyBuffer); Output: replyBuffer: Returned Information. Structure is declared in the header "Server.h". See Appendix III. Returns: Result code (see Appendix I) 3.1.16 GetFileServerLoginStatus (Operator) Returns the default file server's login status. int GetFileServerLoginStatus(int *loginEnabled); Output: loginEnabled: This indicates whether login is enabled (0xff) or disabled (0x00). Logins can be disabled by calling DisableFileServerLogin and subsequently enabled with EnableFileServerLogin. Returns: Result code (see Appendix I) Netware C Library Chapter Three - File Server Services Page: 3-7 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 3.1.17 GetNetworkSerialNumber Returns the default file server's serial number and application number. int GetNetworkSerialNumber(dword *serverSerialNumber , word *appSerialNumber); Output: serverSerialNumber: The file server's serial number. appSerialNumber: The file server's application serial number. Returns: Result code (see Appendix I) 3.1.18 GetPathFromDirectoryEntry Returns the full file path associated with a specified directory entry number on a particular volume. int GetPathFromDirectoryEntry(byte volumeNumber,int directoryEntry, char *path); Input: volumeNumber: Volume number containing the directory. directoryEntry: The offset in the servers Directory Entry Table. This is returned by GetConnectionsOpenFiles. Output: path: 256-byte null terminated full file path of the directory. Returns: Result code (see Appendix I) 3.1.19 GetPhysicalDiskStatistics (Operator) Returns information about a physical disk. int GetPhysicalDiskStatistics(byte physicalDiskNumber, PHYSICAL_DISK_STATISTICS *replyBuffer); Input: physicalDiskNumber: Physical number of the disk. Output: replyBuffer: Structure containing the disk statistics. It is declared in the header file "Server.h". See Appendix III. Returns: Result code (see Appendix I) Netware C Library Chapter Three - File Server Services Page: 3-8 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 3.1.20 GetSemaphoreInformation (Operator) This call returns information about the specified semaphore. It must be called repeatedly in order to obtain the full list of all connections that have the semaphore open. int GetSemaphoreInformation( char *semaphoreName, int *sequence,word *openCount, int *semaphoreValue, word *logicalConnection, word *taskNumber ); Input: semaphoreName: The name of the semaphore for which information is to be retrieved. sequence: On the initial call, this must be zero. On all subsequent calls this must be the value that was returned by the previous call. Output: sequence: Next sequence number to use. When this is set to -1, there are no more connections. openCount: This is the number of logical connections that have this semaphore open. semaphoreValue: This is the current value of the semaphore, in the range -127 to 127. A negative value is the number of applications that are currently waiting for the semaphore, a positive value is the number of applications that can still use the semaphore. logicalConnection: This is the logical connection using the semaphore. taskNumber: This is the task number within the logical connection that has the semaphore open. Returns: Result code (see Appendix I) 3.1.21 SendConsoleBroadcast (Operator) Send a message to a number of logical connections. int SendConsoleBroadcast( byte connectionCount, byte *connections, char *message ); Input: connectionCount: Number of connections that are to receive the message. If this is zero then all attached workstations are broadcast to. Maximum number of connections that can be broadcast is 100. connections: List of connections to which message is to be sent. Must contain "connectionCount" entries. message: 60-byte null terminated message to send to the specified connections. Returns: Result code (see Appendix I) Netware C Library Chapter Four - Connection Services Page: 4-1 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 4. Connection Services These services allow applications to connect to a file server and to obtain information about current connections. 4.1 Connection Functions 4.1.1 AttachToFileServer Attaches the workstation to the specified file server. The workstation must already be logged into at least one server, and can be attached to as many as eight. int AttachToFileServer(char *serverName); Input: serverName: Name of server to attach to Returns: Result code (see Appendix I) 4.1.2 DetachFromFileServer Detaches the workstation from the specified file server. int DetachFromFileServer(char *serverName); Input: serverName: Name of server to detach from Returns: Result code (see Appendix I) 4.1.3 EnterLoginArea Puts the workstation in the server's SYS:LOGIN directory and tells Netware the name of the subdirectory beneath SYS:LOGIN in which the login utility is located. int EnterLoginArea(int numberOfLocalDrives, char *loginDirectoryName); Input: numberOfLocalDrives: Used to determine the workstation drive ID to assign to SYS: ( See GetNumberOfLocalDrives ) loginDirectoryName: 256-byte null terminated ASCII string containing the name of the subdirectory. Returns: Result code (see Appendix I) Netware C Library Chapter Four - Connection Services Page: 4-2 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 4.1.4 GetConnectionInformation Returns information about the user logged in on a connection. int GetConnectionInformation(word connectNo,char *objectName, int *objectType,long *objectID,byte *loginTime); Input: connectNo: Logical connection number Output: objectName: 48-byte null terminated name of logged in object. objectType: Bindery object type of the logged in object. objectID: Bindery object identification of logged object loginTime: Date and time the bindery object logged in: Byte: 0 Year (0 to 99, where 80=1980,81=1981 etc. however a value less than 80 is considered to be in the 21st century) 1 Month (1 to 12) 2 Day (1 to 31) 3 Hour (0 to 23) 4 Minute (0 to 59) 5 Second (0 to 59) 6 Week Day (0 to 6, where 0=Sunday etc.) Returns: Result code (see Appendix I) 4.1.5 GetConnectionNumber Returns the connection number of the requesting workstation. int GetConnectionNumber(void); Returns: Workstations connection number (1-100) or zero if the workstation shell is not loaded. 4.1.6 GetInternetAddress Returns a connections internetwork address. int GetInternetAddress(int conn_no,byte *networkNumber, byte *nodeAddress,word *socketNumber); Input: conn_no: Logical connection number Output: networkNumber: 4-byte number identifying the file server the workstation is physically attached to. nodeAddress: 6-byte address of the workstations LAN board. socketNumber: This is the socket that the workstation uses to communicate with the file server. This socket must not be used by other applications. Returns: Result code (see Appendix I) Netware C Library Chapter Four - Connection Services Page: 4-3 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 4.1.7 GetObjectConnectionNumbers Returns a list of upto 100 connection numbers indicating how many times and under what connection numbers a bindery object is logged in to the default file server. int GetObjectConnectionNumbers(word objType,char *objName, word *connectionCount, byte *connections); Input: objType: Bindery object type objName: 48-byte null terminated Object Name Output: connectionCount: Number of connections connections: List of connection numbers, each one is 1 byte. Returns: Result code (see Appendix I) 4.1.8 GetStationAddress Returns the physical node address of the requesting workstation. void GetStationAddress(byte *physicalNodeAddress); Output: physicalNodeAddress: 6-byte physical address of the workstation. 4.1.9 LoginObjectEncrypted Logs a bindery object into the default file server using encrypted passwords.This function must be used instead of LoginToFileServer if the version of Netware running on the default file server uses encrypted passwords. See the EncryptPassword function in the File Server Environment Services chapter. int LoginObjectEncrypted(word objectType,char *objectName, byte *encryptedPassword) Input: objectType: Bindery object type (see Bindery Objects in Bindery Services) objectName: 48-byte null terminated Object name encryptedPassword: 8-byte encrypted password, returned by EncryptPassword. Returns: Result code (see Appendix I) Netware C Library Chapter Four - Connection Services Page: 4-4 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 4.1.10 LoginToFileServer Log a bindery object into the default file server. int LoginToFileServer(word objectType,char *objectName, char *objectPassword); Input: objectType: Bindery object type (see Bindery Objects in Bindery Services) objectName: 48-byte null terminated Object name objectPassword: 128-byte null terminated Object password. Returns: Result code (see Appendix I) 4.1.11 LogoutFromFileServer This logs the object out from the specified server, but does not detach the workstation from the server. void LogoutFromFileServer(char *serverName); Input: serverName: 48-byte null terminated Name of file server to log out of. 4.1.12 Logout This closes all open files belonging to the object, and logs the object out from all files servers. It then detaches the workstation from all servers except the default one. void Logout(void); Netware C Library Chapter Five - Workstation Services Page: 5-1 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 5. Workstation Services These functions enable programs to get information about several tables that are maintained by the workstation shell. 5.1 Multiple Servers When multiple file servers are used, then the following algorithm is used by Netware to determine which server to send the request to. 1) If the function call requires a drive letter or a connection ID then the Server to which this points is used. 2) If a preferred file server has been set using a call to SetPreferredConnectionID, then send the request to this server. 3) If the default drive is a network drive, then send the request to the server associated with this drive. 4) Send the request to the primary server, which is the server the workstation is logged into unless changed by a call to SetPrimaryConnectionID. 5) Send the request to the first server in the Server Name Table. This is only if the connection to the primary server has been lost. 5.2 Workstation Functions 5.2.1 EndOfJob The workstation shell will automatically issue this call when a program exits (i.e. DOS functions 0x00 and 0x4c are actioned ), so that the workstation environment will be reset. All resources used on the server, ( open files, locks etc. ), will be released. void EndOfJob(void); 5.2.2 GetConnectionIDTable This returns the workstation shells Connection ID Table. The structure ConnectionIDTable is defined in the header file "wstation.h" int GetConnectionIDTable(CONNECTION_ID_TABLE *table); Output: table: Structure containing the connection ID table for each attached server. This must be setup with at least eight elements. It is declared in the header file "wstation.h". See Appendix III. Netware C Library Chapter Five - Workstation Services Page: 5-2 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 5.2.3 GetDefaultConnectionID Returns the connection ID (1-8) of the file server to which request packets are currently being sent. int GetDefaultConnectionID(void); Returns: Default server connection ID (1-8) 5.2.4 GetDriveConnectionID This returns the workstation shells Drive Connection ID Table. It consists of 32 1-byte entries and each entry contains the connection ID of the server that is associated with that drive. A value of zero indicates that the drive is not mapped to a file server, i.e. it is a local drive or it is not used. void GetDriveConnectionID(char *table); Output: table: 32-byte string containing Drive Connection ID Table. 5.2.5 GetDriveFlagTable This returns the workstation shells Drive Flag Table. It consists of 32 1-byte entries and each entry contains the current status of the drive. 0x00 Not allocated 0x01 Permanent Network drive 0x02 Temporary Network drive 0x80 Local drive 0x81 Local drive allocated as a permanent Network drive 0x82 Local drive allocated as a temporary Network drive void GetDriveFlagTable(char *table); Output: table: 32-byte string containing the Drive Flag Table. 5.2.6 GetDriveHandleTable Returns the workstation shells Drive Handle Table. It consists of 32 1-byte entries and each entry contains the directory handle on the file server. A value of zero indicates a drive is not mapped to a directory. void GetDriveHandleTable(char *table); Output: table: 32-byte string containing the Drive Handle Table. Netware C Library Chapter Five - Workstation Services Page: 5-3 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 5.2.7 GetFileServerTable Returns the workstation shells File Server Name Table. It consists of 8 48-byte entries and each entry contains a null-terminated server name. void GetFileServerTable(char *table); Output: table: 384-byte string containing the File Server Name Table. 5.2.8 GetNetwareShellVersion Returns information about the workstations shell. void GetNetwareShellVersion(char *shellInfo, byte *majorVersion,byte *minorVersion, byte *revisionLevel); Output: shellInfo: 40-byte string containing the following four null-terminated strings: 1) Operating system type 2) Operating system version 3) Hardware type 4) Short hardware type majorVersion: Contains the major version number of the workstations shell. minorVersion: Contains the minor version number of the workstations shell. revisionLevel: Contains the revision number of the shell. 1 = A, 2 = B etc. 5.2.9 GetNumberOfLocalDrives Returns the number of local drives on the workstation. int GetNumberOfLocalDrives(void); Returns: Number of local drives. 5.2.10 GetPreferredConnectionID This returns the connection ID of the preferred file server. int GetPreferredConnectionID(void); Returns: The connection ID (1-8) of the Preferred File Server. This has been set by calling SetPreferredConnectionID. Netware C Library Chapter Five - Workstation Services Page: 5-4 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 5.2.11 GetPrimaryConnectionID This returns the connection ID of the primary file server. int GetPrimaryConnectionID(void); Returns: The connection ID (1-8) of the Primary File Server. This has been set by calling SetPrimaryConnectionID. 5.2.12 GetServerConnectionID Get the connection ID of the specified server. int GetServerConnectionID(char *serverName,int *connectionID); Input: serverName: 48-byte null terminated server name Output: connectionID: The connection ID of the specified server (1-8) Returns: Result code (see Appendix I) 5.2.13 IsShellLoaded Checks whether a netware shell is loaded in the workstation. int IsShellLoaded(void); Returns: 0x00 - Shell Loaded 0xbb - No Shell Loaded 5.2.14 SetEndofJobStatus This enables\disables the end of job performed automatically by the workstation shell when control returns to "COMMAND.COM". int SetEndofJobStatus(int NewStatus); Input: NewStatus: New end of job flag, 0 = Disabled, 1 = Enabled. Returns: Original end of job flag. Netware C Library Chapter Five - Workstation Services Page: 5-5 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 5.2.15 SetNWErrorMode This sets the workstation shell to determine how it should respond to DOS emulation call errors. It has three modes :- Mode: 0 This is the default, it uses the normal response format used by DOS. (i.e. "Abort, Retry, Fail") 1 This will not invoke the normal INT 24h handler, but will return the error code for all file I/O calls in AL. 2 The shell will attempt to map the Netware error code to a DOS error code and return it. int SetNWErrorMode(int NewMode); Input: NewMode: New error mode. Returns: Original error mode. 5.2.16 SetPreferredConnectionID This sets the preferred file server. void SetPreferredConnectionID(int connection_id); Input: connection_id: The connection ID (1-8) of the preferred server. 5.2.17 SetPrimaryConnectionID This sets the primary file server. void SetPrimaryConnectionID(int connection_id); Input: connection_id: The connection ID (1-8) of the primary server. Netware C Library Chapter Six - Message Services Page: 6-1 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 6. Message Services These calls enable applications to send messages to specified connections. The sending and destination stations must both be attached to the same server. The messages can either be broadcast messages or pipe messages. Each connection on a file server has a 55-byte message buffer which is used for broadcast messages, and a six slot message queue for pipe messages where each slot can hold a 126-byte message. Before pipe messages can be used, the sending and receiving connections must open a message pipe with the OpenMessagePipe function. 6.1 Message Functions 6.1.1 BroadcastToConsole Broadcast a message to the default file servers system console. int BroadcastToConsole(char *message); Input: message: 60-byte null terminated string containing message to broadcast on the servers console. Returns: Result code (see Appendix I) 6.1.2 CheckPipeStatus This call enables the status of one or more message pipes to be checked. int CheckPipeStatus(byte connectionCount,byte *connections, byte *pipeStatus); Input: connectionCount: Number of message pipes (1-100) that are to be checked. connections: List of the connections whose message pipe is to be checked. There must be "connectionCount" entries, and each entry has a corresponding entry in the "pipeStatus" below. Output: pipeStatus: This contains a code for each specified connection. 0x00 OPEN. The message pipe is complete at both ends. 0xfe INCOMPLETE. The target connections half of the message pipe does not exist. 0xff CLOSED. The callers half of the message pipe does not exist, or the connection number is not in use or is invalid. Returns: Result code (see Appendix I) Netware C Library Chapter Six - Message Services Page: 6-2 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 6.1.3 CloseMessagePipe This call closes this workstations half of one or more message pipes. int CloseMessagePipe(byte connectionCount,byte *connections, byte *resultCodes); Input: connectionCount: Number of message pipes (1-100) that are to be closed. connections: List of the connections whose message pipe is to be closed. There must be "connectionCount" entries, and each entry has a corresponding entry in the "resultCodes" below. Output: resultCodes: This contains a code for each specified connection. 0x00 Successful. The message pipe was successfully closed. 0xfd Failure. The target connection is no longer valid. 0xff No Pipe. There is no pipe to close. Returns: Result code (see Appendix I) 6.1.4 GetBroadcastMessage This is used to poll for and retrieve a broadcast message from the default file server. int GetBroadcastMessage(char *message) Output: message: 56-byte null terminated retrieved message. If the returned message has a length of zero then there was no message waiting. Returns: Result code (see Appendix I) Netware C Library Chapter Six - Message Services Page: 6-3 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 6.1.5 GetBroadcastMode Returns the message mode of the requesting workstation. int GetBroadcastMode(void); Returns: Message mode which can be one of the following :- 0x00 Attached servers will store both user and server messages intended for this workstation. The workstation shell will automatically retrieve and display these messages. 0x01 Attached servers will store server messages intended for this workstation, but all user messages will be discarded. The workstation shell will automatically retrieve and display these messages. 0x02 Attached servers will store server messages intended for this workstation, but all user messages will be discarded. The workstation shell will not retrieve these messages automatically, but a program can call GetBroadcastMessage to poll for and retrieve the most recently stored message. 0x03 Attached servers will store both user and server messages intended for this workstation. The workstation shell will not retrieve these messages automatically, but a program can poll for and retrieve the most recently stored message by making a call to GetBroadcastMessage. 6.1.6 GetPersonalMessage This retrieves the oldest message from this connections pipe queue on the default file server. int GetPersonalMessage(char *message,byte *sourceConnection); Output: message: 126-byte null terminated retrieved message. If the returned message has a length of zero then there was no message in the pipe queue. sourceConnection: This is the connection number of the sending station. If this is zero then there was no message in the pipe queue. Returns: Result code (see Appendix I) Netware C Library Chapter Six - Message Services Page: 6-4 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 6.1.7 LogNetworkMessage This logs a message in the default file servers NET$LOG.MSG file which is held in the SYS:SYSTEM directory. The message is automatically prefixed with the date and time and logical connection number. void LogNetworkMessage(char *message); Input: message: 80-byte null terminated message to write to the log file. 6.1.8 OpenMessagePipe This creates the calling connections half of one or more message pipes. Before 2 connections can exchange pipe messages, both must establish a connection by calling this function. int OpenMessagePipe(byte connectionCount,byte *connections, byte *resultCodes); Input: connectionCount:Number of connections (1-100) to which this workstation opens a pipe. connections: List of the connections to which this workstation opens a pipe. Output: resultCodes: This contains a result code for each connection specified in the "connections" field: 0x00 Successful. The message pipe is complete at both ends. 0xfe Incomplete Pipe. The connections has not yet created its half of the pipe. 0xff Failure. The connection is not valid, or the connection is not in use. Returns: Result code (see Appendix I) 6.1.9 SendBroadcastMessage This sends a broadcast message to the specified connections on the default file server. int SendBroadcastMessage( byte connectionCount,byte *connections, char *message , byte *resultCodes); Input: connectionCount:Number of connections (1-100) that are to be broadcast. connections: List of the connections who are to receive the broadcast message. message: 55-byte null terminated message to be broadcast. Netware C Library Chapter Six - Message Services Page: 6-5 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Output: resultCodes: This contains a result code for each connection specified in the "connections" field: 0x00 Successful. The message was stored in the connections message buffer. 0xfc Rejected. The connections message buffer already contains a message. 0xfd Invalid Connection. The connection number is not known. 0xff Blocked. The connections message mode is set to block messages, or the connection is not in use. Returns: Result code (see Appendix I) 6.1.10 SendPersonalMessage This sends a pipe message to the specified connections on the default file server. Before this can be called, the procedure OpenPipeMessage must have been called by both the sending and receiving workstations. int SendPersonalMessage( byte connectionCount,byte *connections, char *message , byte *resultCodes); Input: connectionCount:Number of connections (1-100) that are to receive the message. connections: List of the connections who are to receive the message. message: 126-byte null terminated message to be sent. Output: resultCodes: This contains a result code for each connection specified in the "connections" field: 0x00 Successful. The message was stored in the connections pipe queue. 0xfc Rejected. The connections pipe queue is full (six slots already in use). 0xfe Incomplete Pipe. The connections pipe half does not exist. 0xff Failure. The source connectiosn pipe half does not exist, or the connection number is not in use. Returns: Result code (see Appendix I) Netware C Library Chapter Six - Message Services Page: 6-6 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 6.1.11 SetBroadcastMode Set the message mode for the requesting workstation. int SetBroadcastMode(int messageMode); Input: messageMode: Message mode to set :- 0x00 Attached servers will store both user and server messages intended for this workstation. The workstation shell will automatically retrieve and display these messages. 0x01 Attached servers will store server messages intended for this workstation, but all user messages will be discarded. The workstation shell will automatically retrieve and display these messages. 0x02 Attached servers will store server messages intended for this workstation, but all user messages will be discarded. The workstation shell will not retrieve these messages automatically, but a program can call GetBroadcastMessage to poll for and retrieve the most recently stored message. 0x03 Attached servers will store both user and server messages intended for this workstation. The workstation shell will not retrieve these messages automatically, but a program can poll for and retrieve the most recently stored message by making a call to GetBroadcastMessage. Returns: Message mode that was set. Netware C Library Chapter Seven - File Services Page: 7-1 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 7. File Services The file services include calls that enable applications to manipulate extended file attributes, restore erased files, permanently delete files and set file information. 7. 1 Directory Handles Most of the calls in the File services identify files by specifying a file path and a directory handle. A directory handle is a value from 1 to 255 which references a volume or directory. For the function calls that require a directory handle then zero can be supplied, but the volume name must be specified in the file path. For more information about directory handles and where they are stored then see the section on Directory Services. 7.2 Search Attributes Some functions within the File services can act on normal, hidden, or system files. These depend on the value of the search attributes parameter. The following values can be supplied :- 0 - Normal files only 2 - Normal and Hidden files 4 - Normal and System files 6 - Normal, Hidden and System files 7.3 File Attributes These are held as 1 byte, and contain the following settings: Bits 7 6 5 4 3 2 1 0 - - - - - - - x Read only - - - - - - x - Hidden File (not shown on directory listing) - - - - - x - - System File (not shown on directory listing) - - - - x - - - Execute only - - - x - - - - Entry is a subdirectory - - x - - - - - Needs to be archived - x - - - - - - Not used x - - - - - - - File is shareable Netware C Library Chapter Seven - File Services Page: 7-2 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 7.4 Extended File Attributes These, like the file attributes, are held as 1 byte, and contain the following settings: Bits 7 6 5 4 3 2 1 0 - - - - - x x x Search mode bits (see below) - - - - x - - - Reserved - - - x - - - - Transaction bit ( used by TTS ) - - x - - - - - Index bit (file allocation table is indexed for faster access, should be set if the file is larger than 2 MB) - x - - - - - - Read audit bit ( not used currently ) x - - - - - - - Write audit bit ( not used currently ) The search mode bits are only applicable for executable files, they specify how the Netware shell should search for any files that this file opens whilst it is running. The following values are defined: 0 No mode, use the shell's default search mode. 1 Search for files in the current directory and then in the current search drives, only if no path is specified. 2 Search for files in the current directory only. 3 Search current directory and then in the current search drives, only if the file is being opened in read-only mode and no path has been specified. 5 Search for files in the current directory and then in the current search drives regardless of whether a drive or directory is specified. 7 Search for files in the current directory and then in the current search drives regardless of whether a drive or directory is specified, but only if the file is being opened in read-only mode. 7.5 File Functions 7.5.1 EraseFiles This marks the specified file for deletion. int EraseFiles( byte searchAttributes, byte directoryHandle,char *filePath); Input: searchAttributes: This is the type of file to be deleted. directoryHandle: An optional directory handle, pointing to an entry in the servers Directory Handle Table. filePath: 256-byte null terminated directory path name. This can either be a full path name, i.e. VOLUME:DIR\..\DIR in which case the directory handle must be 0x00, or a partial directory name which will be used in conjunction with the directory handle. Returns: Result code (see Appendix I) Netware C Library Chapter Seven - File Services Page: 7-3 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 7.5.2 PurgeAllErasedFiles (Operator) This permanently deletes all files marked for deletion by all workstations on the network. int PurgeAllErasedFiles(void); Returns: Result code (see Appendix I) 7.5.3 PurgeErasedFiles This permanently deletes all files marked for deletion by this workstation. int PurgeErasedFiles(void); Returns: Result code (see Appendix I) 7.5.4 ScanFileInformation Return information about the specified file. This call can be made iteratively to return information about a group of files by including wildcards in the filepath. int ScanFileInformation(byte directoryHandle, char *filePath, byte searchAttributes,int *sequenceNumber, char *fileName,byte *fileAttributes, byte *extendedFileAttributes,long *fileSize, char *creationDate,char *lastAccessDate, char *lastUpdateDateAndTime, char *lastArchiveDateAndTime, long *fileOwnerId) Input: directoryHandle: An optional directory handle, pointing to an entry in the servers Directory Handle Table. If "filePath" contains the full path name then this must be 0x00. filePath: 256-byte null terminated directory path name. This can either be a full path name, i.e. VOLUME:DIR\..\DIR in which case source directory handle must be 0x00, or a partial directory name which will be used in conjunction with the directory handle. searchAttributes: This is the type of file to be scanned for. (see section 7.2) sequenceNumber: On the first call this must contain -1. Do not alter for subsequent calls. Output: sequenceNumber: Returns the sequence number of the next file. fileName: 15-byte null terminated file name. fileAttributes: Files attributes (see section 7.3) extendedFileAttributes: Extended attributes (see section 7.4) Netware C Library Chapter Seven - File Services Page: 7-4 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ fileSize: This is the size of the file in bytes. creationDate: Date the file was created: Byte 0 Year (0 to 99, where 80=1980, 1=1981 etc. Howver a value less than 80 is considered to be in the 21st century.) 1 Month (1 to 12) 2 Day (1 to 31) lastAccessDate: Date the file was last accessed. Same format as "creationDate". lastUpdateDateAndTime: Date and time the file was last updated: Byte 0 Year (0 to 99, where 80=1980, 1=1981 etc. Howver a value less than 80 is considered to be in the 21st century.) 1 Month (1 to 12) 2 Day (1 to 31) 3 Hour (0 to 23) 4 Minute (0 to 59) 5 Second (0 to 59) lastArchiveDateAndTime: Date and time the file was last archived. same format as "lastUpdateDateAndTime". fileOwnerId: The bindery object ID of the user who created the file. Returns: Result code (see Appendix I) Netware C Library Chapter Eight - Directory Services Page: 8-1 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 8. Directory Services These calls can allocate and deallocate directory handles; create, rename and destroy directories; add and delete directory trustees; return information about volumes and directories; and modify a directories maximum rights mask. 8.1 Directory Handle Table Every connection on a file server has the ability to have up to 256 directory handles, these are held on the server in the Directory Handle Table, one table for each connection, each table contains 256 slots where each slot represents a directory handle. A directory handle is a number, 1 to 255, that points to a volume or a directory path. Once a directory handle has been set this can be used when a volume or directory path needs to be specified. 8.2 Drive Handle Table This is maintained by the workstations shell program. It contains 32 1-byte entries. The first 26 slots represent the permanent drive letters A-Z, the last six slots represent the temporary drive letters:- [ (left square bracket) \ (backslash) ] (right square bracket) ^ (caret) _ (underline) ' (apostrophe) Each slot in the table contains a directory handle number. 8.3 Drive Flag Table This is maintained by the workstations shell program. It contains 32 1-byte entries. The first 26 slots represent the permanent drive letters A-Z, the last six slots represent the temporary drive letters:- [ (left square bracket) \ (backslash) ] (right square bracket) ^ (caret) _ (underline) ' (apostrophe) Each slot in the table contains a value which defines the type of drive: 0x00 Not allocated 0x01 Permanent Network drive 0x02 Temporary Network drive 0x80 Local drive 0x81 Local drive allocated as a permanent network drive 0x82 Local drive allocated as a temporary network drive Netware C Library Chapter Eight - Directory Services Page: 8-2 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 8.4 Drive Connection ID Table This is maintained by the workstations shell program. It contains 32 1-byte entries. The first 26 slots represent the permanent drive letters A-Z, the last six slots represent the temporary drive letters:- [ (left square bracket) \ (backslash) ] (right square bracket) ^ (caret) _ (underline) ' (apostrophe) Each slot contains a value, 0 to 8, identifying the server to which the drive letter is mapped. A value of 0 indicates that the drive is not mapped, a value of 1-8 represents the position of the server in the workstations Server Name Table. 8.5 Trustee Rights A users trustee rights and a directories maximum rights are held as 1 byte consisting of the following settings:- (MSB) Bit 7: Modify (file attributes can be modified) 6: Search (directory can be searched) 5: Parental (subdirectories can be created/deleted & trustee rights granted/revoked) 4: Delete (files can be deleted) 3: Create (files can be created) 2: Open (files can be opened) 1: Write (file writes allowed) (LSB) 0: Read (file reads allowed) When a users trustee rights and a directories maximum rights mask are logically anded together, they produce a users effective rights in the specified directory. 8.6 Directory Functions 8.6.1 AddTrusteeToDirectory Add a trustee to a directories trustee list. The requesting workstation must have parental rights to the target directory, or to a parent directory. int AddTrusteeToDirectory(byte directoryHandle,char *directoryPath, long trusteeObjectID, byte trusteeRightsMask); Input: directoryHandle: An optional directory handle, pointing to an entry in the servers Directory Handle Table. If "directoryPath" contains the full pathname then this must be 0x00. Netware C Library Chapter Eight - Directory Services Page: 8-3 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ directoryPath: 256-byte null terminated directory path name. This can either be a full path name, i.e. VOLUME:DIR\..\DIR or a partial name containing at least a directory name. trusteeObjectID: Bindery object ID of user name to add to the specified directories trustee list. trusteeRightsMask: The rights mask to be given to the user. If the user is already a trustee in the specified directory, then this replaces the existing rights. Returns: Result code (see Appendix I) 8.6.2 AllocPermanentDirectoryHandle Permanently assign a workstation drive to a network directory. int AllocPermanentDirectoryHandle(byte directoryHandle, char *directoryPath, char driveLetter, byte *newDirectoryHandle, byte *effectiveRightsMask); Input: directoryHandle: An optional directory handle, pointing to an entry in the servers Directory Handle Table. If "directoryPath" contains the full path name then this must be 0x00. directoryPath: 256-byte null terminated directory path name. This can either be a full path name, i.e. VOLUME:DIR\..\DIR or a partial name containing at least a directory name. driveLetter: Drive letter to assign to the specified directory. Output: newDirectoryHandle: The new directory handle pointing to the specified directory. effectiveRightsMask: This is the result of logically anding the users trustee rights with the directories maximum rights. Returns: Result code (see Appendix I) 8.6.3 AllocTemporaryDirectoryHandle Temporarily assign a workstation drive to a network directory. The allocation is only valid until the application executes an EndOfJob, or until the job deallocates the drive with DeallocateDirectoryHandle. int AllocTemporaryDirectoryHandle(byte directoryHandle, char *directoryPath, char driveLetter, byte *newDirectoryHandle, byte *effectiveRightsMask); Netware C Library Chapter Eight - Directory Services Page: 8-4 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Input: directoryHandle: An optional directory handle, pointing to an entry in the servers Directory Handle Table. If "directoryPath" contains the full path name then this must be 0x00. directoryPath: 256-byte null terminated directory path name. This can either be a full path name, i.e. VOLUME:DIR\..\DIR or a partial name containing at least a directory name. driveLetter: Drive letter to assign to the specified directory. Output: newDirectoryHandle: The new directory handle pointing to the specified directory. effectiveRightsMask: This is the result of logically anding the users trustee rights with the directories maximum rights. Returns: Result code (see Appendix I) 8.6.4 CreateDirectory This creates a subdirectory under the directory which is pointed to by "directoryHandle". int CreateDirectory(byte directoryHandle,byte maximumRightsMask, char *directoryPath); Input: directoryHandle: An optional directory handle, pointing to an entry in the servers Directory Handle Table. If "directoryPath" contains the full path name then this must be 0x00. maximumRightsMask: This indicates the maximu rights that a user can have in this directory. directoryPath: 256-byte null terminated directory path name. This can either be a full path name, i.e. VOLUME:DIR\..\DIR or a partial name containing at least a directory name. Returns: Result code (see Appendix I) 8.6.5 DeallocateDirectoryHandle Deallocate a permanent or temporary directory handle. int DeallocateDirectoryHandle(byte directoryHandle); Input: directoryHandle: Directory handle to deallocate. Returns: Result code (see Appendix I) Netware C Library Chapter Eight - Directory Services Page: 8-5 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 8.6.6 DeleteDirectory int DeleteDirectory(byte directoryHandle,char *directoryPath); Input: directoryHandle: An optional directory handle, pointing to an entry in the servers Directory Handle Table. If "directoryPath" contains the full path name then this must be 0x00. directoryPath: 256-byte null terminated directory path name. This can either be a full path name, i.e. VOLUME:DIR\..\DIR or a partial name containing at least a directory name. Returns: Result code (see Appendix I) 8.6.7 DeleteFakeRoot This call deletes a fake root, that was created using MapFakeRoot. void DeleteFakeRoot(byte drive); Input: drive: Drive number to remove ( 0 = current, 1 = A , 2 = B etc. ) 8.6.8 DeleteTrusteeFromDirectory This removes a trustee form a directorys trustee list. int DeleteTrusteeFromDirectory(byte directoryHandle, char *directoryPath, long trusteeObjectID); Input: directoryHandle: An optional directory handle, pointing to an entry in the servers Directory Handle Table. If "directoryPath" contains the full path name then this must be 0x00. directoryPath: 256-byte null terminated directory path name. This can either be a full path name, i.e. VOLUME:DIR\..\DIR or a partial name containing at least a directory name. trusteeObjectID: Bindery object ID of user name to remove from the specified directories trustee list. Returns: Result code (see Appendix I) Netware C Library Chapter Eight - Directory Services Page: 8-6 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 8.6.9 GetCurrentDirectory This returns the current directory for the given drive. int GetCurrentDirectory(char driveNumber,char *directoryPath); Input: driveNumber: Drive number whose current directory is to be returned. (0 to 25 = A-Z, 26 to 31 = [\]^_') Output: directoryPath: 256-byte null terminated current path of specified drive. Returns: Result code (see Appendix I) 8.6.10 GetDirectoryHandle Returns the directory handle of the given drive. int GetDirectoryHandle(char driveNumber,byte *statusFlags); Input: driveNumber: Drive number whose handle is to be returned. (0 to 25 = A-Z, 26 to 31 = [\]^_' ) Output: statusFlags: This is 1-byte with the following bits defined:- (MSB) Bit 7: Mapped to a local drive 6-2: Unused 1: Temporary directory handle (LSB) 0: Permanent directory handle Returns: Directory Handle (1 to 255), or zero if drive number is invalid. 8.6.11 GetDirectoryPath Returns the directory path of the specified handle. int GetDirectoryPath(byte directoryHandle,char *directoryPath); Input: directoryHandle: Directory handle whose path is to be returned. Output: directoryPath: 256-byte null terminated full path name. Returns: Result code (see Appendix I) Netware C Library Chapter Eight - Directory Services Page: 8-7 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 8.6.12 GetEffectiveDirectoryRights Returns the current users effective rights to the directory. int GetEffectiveDirectoryRights(byte directoryHandle, char *directoryPath, byte *effectiveRights); Input: directoryHandle: An optional directory handle, pointing to an entry in the servers Directory Handle Table. If "directoryPath" contains the full path name then this must be 0x00. directoryPath: 256-byte null terminated directory path name. This can either be a full path name, i.e. VOLUME:DIR\..\DIR or a partial name containing at least a directory name. Output: effectiveRights: Users effective rights in this directory. Returns: Result code (see Appendix I) 8.6.13 GetVolumeInformation This returns information about the specified volume. The structure VolumeStatistics is defined in the header file "Direct.h" int GetVolumeInformation(byte volumeNumber, VOLUME_STATISTICS *replyBuffer); Input: volumeNumber: This identifies the volume in the file servers Volume Table. Output: replyBuffer: Structure containing the volume statistics. It is declared in the header file "Direct.h". See Appendix III. Returns: Result code (see Appendix I) Netware C Library Chapter Eight - Directory Services Page: 8-8 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 8.6.14 GetVolumeInfoWithHandle This returns information about a volume using a directory handle. int GetVolumeInfoWithHandle(byte directoryHandle, char *volumeName, word *sectorsPerBlock, word *totalBlocks, word *availableBlocks, word *totalDirectorySlots, word *availableDirectorySlots, int *volumeIsRemovable); Input: directoryHandle: Directory handle pointing to an entry in the servers Directory Handle Table. Output: volumeName: 17-byte null terminated volume name sectorsPerBlock: This is the number of 512-byte sectors contained in each block of the specified volume. totalBlocks: This is the total number of blocks on the specified volume. availableBlocks: This is the total number of unused blocks on the specified volume. totalDirectorySlots: This is the number of directory slots that the installer allocated. availableDirectorySlots: This is the total number of unused directory slots. volumeIsRemovable: A value of zero indicates that the volume cannot be removed. Returns: Result code (see Appendix I) 8.6.15 GetVolumeInfoWithNumber This returns information about a volume using a volume number. int GetVolumeInfoWithNumber(byte volumeNumber, char *volumeName, word *sectorsPerBlock, word *totalBlocks, word *availableBlocks, word *totalDirectorySlots, word *availableDirectorySlots, int *volumeIsRemovable); Input: volumeNumber: Number of the volume in the servers Volume Name Table. Output: volumeName: 17-byte null terminated volume name sectorsPerBlock: This is the number of 512-byte sectors contained in each block of the specified volume. Netware C Library Chapter Eight - Directory Services Page: 8-9 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ totalBlocks: This is the total number of blocks on the specified volume. availableBlocks: This is the total number of unused blocks on the specified volume. totalDirectorySlots: This is the number of directory slots that the installer allocated. availableDirectorySlots: This is the total number of unused directory slots. volumeIsRemovable: A value of zero indicates that the volume cannot be removed. Returns: Result code (see Appendix I) 8.6.16 GetVolumeName This call returns the volume name of the specified volume. int GetVolumeName(int volumeNumber,char *volumeName); Input: volumeNumber: This identifies the volume in the servers volume table, it is an integer in the range 0-31. Output: volumeName: 17-byte null terminated name of the volume. Returns: Result code (see Appendix I) 8.6.17 GetVolumeNumber This call returns the volume number of the specified volume. int GetVolumeNumber(char *volumeName,int *volumeNumber); Input: volumeName: 17-byte null terminated Volume name. Output: volumeNumber: Returned internal number of the specified volume. Returns: Result code (see Appendix I) 8.6.18 MapFakeRoot This call allows you to map any drive as a fake root. If the drive is not currently mapped then this will create the mapping and set the fake root. int MapFakeRoot(byte drive,char *path); Input: drive: Drive number to map ( 0 = current, 1 = A , 2 = B etc. ) path: The full path for the fake root. Returns: Result code (see Appendix I) Netware C Library Chapter Eight - Directory Services Page: 8-10 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 8.6.19 ModifyMaximumRightsMask Modify the maximum rights mask of a specific directory. int ModifyMaximumRightsMask(byte directoryHandle, char *directoryPath,byte revokeRightsMask,byte grantRightsMask); Input: directoryHandle: An optional directory handle, pointing to an entry in the servers Directory Handle Table. If "directoryPath" contains the full path name then this must be 0x00. directoryPath: 256-byte null terminated directory path name. This can either be a full path name, i.e. VOLUME:DIR\..\DIR or a partial name containing at least a directory name. revokeRightsMask: The rights to be removed. grantRightsMask: The rights to be added Returns: Result code (see Appendix I) 8.6.20 RenameDirectory Renames the specified server directory. int RenameDirectory(byte directoryHandle,char *directoryPath, char *newDirectoryName); Input: directoryHandle: An optional directory handle, pointing to an entry in the servers Directory Handle Table. If "directoryPath" contains the full path name then this must be 0x00. directoryPath: 256-byte null terminated directory path name. This can either be a full path name, i.e. VOLUME:DIR\..\DIR or a partial name containing at least a directory name. newDirectoryName: 15-byte null terminated new directory name. Returns: Result code (see Appendix I) 8.6.21 RestoreDirectoryHandle Restores a previously saved directory handle int RestoreDirectoryHandle(char *saveBuffer, byte *newDirectoryHandle,byte *effectiveRightsMask); Input: saveBuffer: 16-byte save buffer. Output: newDirectoryHandle: The directory handle that has been restored. effectiveRightsMask: The users current effective rights here. Returns: Result code (see Appendix I) Netware C Library Chapter Eight - Directory Services Page: 8-11 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 8.6.22 SaveDirectoryHandle Saves a specific directory handle. int SaveDirectoryHandle(byte directoryHandle,char *saveBuffer); Input: directoryHandle: Directory handle to be saved. Output: saveBuffer: 16-byte buffer which contains the saved information. Returns: Result code (see Appendix I) 8.6.23 ScanBinderyObjectTrusteePaths This returns the directory paths to which the specified object has trustee rights. This call must be made repeatedly to obtain all paths. int ScanBinderyObjectTrusteePaths(long objectID,byte volumeNumber, int *sequenceNumber,char *trusteeAccessMask, char *trusteePathName); Input: objectID: Bindery object ID to scan for. volumeNumber: Server volume number to scan (0-31) sequenceNumber: On the first call this must contain zero. Do not alter for subsequent calls. Output: sequenceNumber: Returns the sequence number of the next path. trusteeAccessMask: The rights the object has in this directory. trusteePathName: 256-byte null terminated path name. Returns: Result code (see Appendix I) 8.6.24 ScanDirectoryForTrustees This returns the trustees of the specified directory. This call must be made repeatedly in order to obtain all the trustees of the specified directory. int ScanDirectoryForTrustees( byte directoryHandle,char *directoryPath, int *sequenceNumber,char *directoryName, char *creationDateTime,long *ownerID, long *trusteeID,byte *trusteeRightsMask); Input: directoryHandle: An optional directory handle, pointing to an entry in the servers Directory Handle Table. If "directoryPath" contains the full path name then this must be 0x00. Netware C Library Chapter Eight - Directory Services Page: 8-12 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ directoryPath: 256-byte null terminated directory path name. This can either be a full path name, i.e. VOLUME:DIR\..\DIR or a partial name containing at least a directory name. sequenceNumber: On the first call this must contain zero. Do not alter for subsequent calls. Output: sequenceNumber: Returns the sequence number of the next trustee directoryName: 16-byte name of the directory. creationDateTime: Date and time the directory was created: Byte 0 Year (0 to 99, where 80=1980, 1=1981 etc. Howver a value less than 80 is considered to be in the 21st century.) 1 Month (1 to 12) 2 Day (1 to 31) 3 Hour (0 to 23) 4 Minute (0 to 59) 5 Second (0 to 59) ownerID: The bindery object ID of the user that created this directory. trusteeID: The bindery object ID of a trustee of the directory. trusteeRightsMask:The trustees effective rights in this directory. Returns: Result code (see Appendix I) 8.6.25 ScanDirectoryInformation This returns information about the first or next subdirectory of the specified directory. int ScanDirectoryInformation( byte searchDirectoryHandle,char *searchDirectoryPath, int *subdirNumber,char *directoryName, byte *creationDateTime,long *ownerObjectID, byte *maximumRightsMask); Input: searchDirectoryHandle: An optional directory handle, pointing to an entry in the servers Directory Handle Table. If "searchDirectoryPath" contains the full path name then this must be 0x00. searchDirectoryPath: 256-byte null terminated directory path name. This can either be a full path name i.e. VOLUME:DIR\..\DIR or a partial name containing at least a directory name. The path can contain wildcard characters. Netware C Library Chapter Eight - Directory Services Page: 8-13 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ subdirNumber: On the first call this must contain zero. Do not alter for subsequent calls. Output: subdirNumber: Returns the directory number of the next sub directory. directoryName: 16-byte name of the directory. creationDateTime: Date and time the directory was created: Byte 0 Year (0 to 99, where 80=1980, 1=1981 etc. Howver a value less than 80 is considered to be in the 21st century.) 1 Month (1 to 12) 2 Day (1 to 31) 3 Hour (0 to 23) 4 Minute (0 to 59) 5 Second (0 to 59) ownerObjectID: The bindery object ID of the user that created this directory. maximumRightsMask: This is the maximum rights that any user will have in this subdirectory. See section 8.5 for possible settings. Returns: Result code (see Appendix I) 8.6.26 SetDirectoryHandle Assigns a directory handle to a given path. int SetDirectoryHandle(byte sourceDirectoryHandle, char *sourceDirectoryPath, byte targetDirectoryHandle); Input: sourceDirectoryHandle: An optional directory handle, pointing to an entry in the servers Directory Handle Table. If "sourceDirectoryPath" contains the full path name then this must be 0x00 sourceDirectoryPath: 256-byte null terminated directory path name. This can either be a full path name i.e. VOLUME:DIR\..\DIR in which case source directory handle must be 0x00, or a partial directory name which will be used in conjunction with the source directory handle. targetDirectoryHandle: The directory handle which is to point to the above specified directory. If the call fails, then this will point to its original directory. Returns: Result code (see Appendix I) Netware C Library Chapter Nine - Print Services Page: 9-1 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 9. Print Services These services allow data that is sent to a LPT device, to be captured and redirected to a specific file server. 9.1 Print Functions 9.1.1 CancelLPTCapture This cancels the capture of the default LPT device. The print queue job entry is removed and the capture file is deleted unless it is a permanent file. The LPT device is then returned to local printing mode. int CancelLPTCapture(void); Returns: Result code (see Appendix I) 9.1.2 CancelSpecificLPTCapture This cancels the capture of a specific LPT device. The print queue job entry is removed and the capture file is deleted unless it is a permanent file. The LPT device is then returned to local printing mode. int CancelSpecificLPTCapture(int prnNo); Input: prnNo: LPT device number (0-2,0=LPT1) Returns: Result code (see Appendix I) 9.1.3 EndLPTCapture This call ends the capture of the default LPT device. The capture file will be closed and the queue job entry will be released so that a print service may process it. The LPT device is then returned to local printing mode. int EndLPTCapture(void); Returns: Result code (see Appendix I) 9.1.4 EndSpecificLPTCapture This call ends the capture of a specific LPT device. The capture file will be closed and the queue job entry will be released so that a print service may process it. The LPT device is then returned to local printing mode. int EndSpecificLPTCapture(int prnNo); Input: prnNo: LPT device number (0-2,0=LPT1) Returns: Result code (see Appendix I) Netware C Library Chapter Nine - Print Services Page: 9-2 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 9.1.5 FlushLPTCapture This closes the current capture file of the default LPT device. After this call is made, the default LPT device remains in a captured state. int FlushLPTCapture(void); Returns: Result code (see Appendix I) 9.1.6 FlushSpecificLPTCapture This closes the current capture file of a specific LPT device. After this call is made, the specificied LPT device remains in a captured state. int FlushSpecificLPTCapture(int prnNo); Input: prnNo: LPT device number (0-2, 0=LPT1) Returns: Result code (see Appendix I) 9.1.7 GetBannerUserName Returns the user name that is printed on the banner page. int GetBannerUserName(char *pointer); Output: pointer: 13-byte null terminated user name Returns: Result code (see Appendix I) 9.1.8 GetLPTCaptureStatus This returns whether the default capture is active. int GetLPTCaptureStatus(void); Returns: Capture Status. 0x00 Capture is not active 0xff Capture is active 9.1.9 GetDefaultLocalPrinter This returns the number of the default LPT device. int GetDefaultLocalPrinter(void); Returns: Default LPT device number. 0x00 LPT1 0x01 LPT2 0x02 LPT3 Netware C Library Chapter Nine - Print Services Page: 9-3 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 9.1.10 GetDefaultCaptureFlags Returns the print job flags for the default LPT device. int GetDefaultCaptureFlags(PRINT_CONTROL_DATA *reply); Output: reply: Structure containing flags. See Appendix III. Returns: Result code (see Appendix I) 9.1.11 GetPrinterStatus This returns the current status of the specified server printer. int GetPrinterStatus(int prnNo, byte *printerHalted,byte *printerOffline, byte *formType,byte *targetPrinterNumber); Input: prnNo: Server printer number (0-4). Output: printerHalted: A value of 0x00 indicates that the printer is active, and a value of 0xff if the printer is stopped. printerOffline: A value of 0x01 indicates the printer is offline. formType: This is the form type that is currently in use. targetPrinterNumber: This should be the same as the printer number specified in prnNo, unless the server console has rerouted the printer. Returns: Result code (see Appendix I) 9.1.12 GetSpecificCaptureFlags Returns the print job flags for the specified LPT device. int GetSpecificCaptureFlags(int device,PRINT_CONTROL_DATA *reply); Input: device: LPT device number (0-2, 0=LPT1) Output: reply: Structure containing flags. See Appendix III. Returns: Result code (see Appendix I) Netware C Library Chapter Nine - Print Services Page: 9-4 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 9.1.13 SetBannerUserName Sets the user name that is printed on the banner page. This applies to local LPT devices. int SetBannerUserName(char *pointer); Input: pointer: 13-byte null terminated user name. Returns: Result code (see Appendix I) 9.1.14 SetCapturePrintQueue Sets the target print queue for the next capture of the specified device. int SetCapturePrintQueue(int device,long queueID); Input: device: LPT device number (0-2, 0=LPT1) queueID: This is the bindery object ID of the queue where print jobs are to be sent. Returns: Result code (see Appendix I) 9.1.15 SetDefaultLocalPrinter This sets the default LPT device, for all default local LPT capturing. int SetDefaultLocalPrinter(int device); Input: device: LPT device number (0-2, 0=LPT1) Returns: Result code (see Appendix I) 9.1.16 SetDefaultCaptureFlags Sets the capture flags for the default LPT device. int SetDefaultCaptureFlags(PRINT_CONTROL_DATA *flags); Input: flags: Structure containing flags. See Appendix III. Returns: Result code (see Appendix I) Netware C Library Chapter Nine - Print Services Page: 9-5 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 9.1.17 SetSpecificCaptureFlags Sets the capture flags for the specified LPT device. int SetSpecificCaptureFlags(int device,PRINT_CONTROL_DATA *reply); Input: device: LPT device number (0-2, 0=LPT1) flags: Structure containing flags. See Appendix III. Returns: Result code (see Appendix I) 9.1.18 SpecifyCaptureFile This creates a capture file for the next capture process. int SpecifyCaptureFile(int directoryHandle,char *filename); Input: directoryHandle: An optional directory handle, pointing to an entry in the servers Directory Handle Table. If "filename" contains the full path name then this must be 0x00. filename: 256-byte null terminated file name. This can either be a full path name, i.e. VOLUME:DIR\..\DIR\FILE or a partial name containing at least the terminal name of the file. Returns: Result code (see Appendix I) 9.1.19 StartLPTCapture This starts the capture of the default LPT device. int StartLPTCapture(void); Returns: Result code (see Appendix I) 9.1.20 StartSpecificLPTCapture This starts the capture of the specified LPT device. int StartSpecificLPTCapture(int device); Input: device: LPT device number (0-2, 0=LPT1) Returns: Result code (see Appendix I) Netware C Library Chapter Ten - Synchronisation Services Page: 10-1 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 10. Synchronisation Services These services allow applications to control access to files and other network resources. These are split into two categories: file/record locking and semaphores. This document and associated library currently only covers semaphores, file/record locking functions will be provided in a future release. 10.1 Semaphores A semaphore is a named location that has a value associated with it. The name can be up to 127 bytes long and the value can be in the range -127 to 127. Semaphores are generally used to control access to resources on a network. Before an application can access a semaphore, it must first open it by calling OpenSemaphore, if the semaphore does not already exist then it will be automatically created by this call. OpenSemaphore must be passed an initial value for the semaphore which will only be used if the semaphore is to be created, this value is the number of processes that can access the network resource at any one time and must be in the range 1 to 127. After opening the specified semaphore, the associated open count will be incremented and the value returned to the caller. When the application wishes to access the resource associated with the semaphore, it must first call WaitOnSemaphore. When WaitOnSemaphore is called, the value associated with the semaphore is decremented. If this value is still positive, i.e. greater than or equal to zero, then a zero response is returned indicating that the resource is available otherwise the application will be placed in a queue and a wait will be performed for the specified period. If the semaphore value should become positive during the wait, i.e. another application has released it, then the wait will be terminated and a zero response will be returned. If the semaphore value is still negative at the end of the wait, then the application is removed from the queue, the semaphore value will be incremented and a failing response will be returned indicating that the resource is not available. After an application has finished with the resource, it must call SignalSemaphore in order to increment the semaphore value. Before the application terminates it must call CloseSemaphore in order to decrement the open count associated with the semaphore. If this count should become zero then the semaphore will be automatically deleted. The current value and open count of a semaphore can be obtained by calling ExamineSemaphore. The semaphore does not need to be opened by the application in order to call this. Netware C Library Chapter Ten - Synchronisation Services Page: 10-2 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 10.2 Synchronisation Functions 10.2.1 CloseSemaphore This decrements the semaphore's open count, if the count becomes zero then the semaphore will be deleted. int CloseSemaphore( long semaphoreHandle ); Input: semaphoreHandle: Handle returned from the call to OpenSemaphore. Returns: Result code (see Appendix I) 10.2.2 ExamineSemaphore Returns the current open count and value of the specified semaphore. int ExamineSemaphore( long semaphoreHandle, int *semaphoreValue,word *openCount); Input: semaphoreHandle: Handle returned from the call to OpenSemaphore. Output: semaphoreValue: Current semaphore value, in the range -127 to 127. A positive value indicates that applications can access the resource associated with this semaphore, a negative value indicates that there is currently a queue of processes waiting for the semaphore to become free. openCount: The current number of processes that have this semaphore open. Returns: Result code (see Appendix I) 10.2.3 OpenSemaphore This opens/creates the specified semaphore. int OpenSemaphore( char *semaphoreName,int initialValue, long *semaphoreHandle,word *openCount); Input: semaphoreName: Name of the semaphore to be opened. initialValue: The value to be given to the semaphore if it is created. i.e. the number of applications that can simultaneously access the resource that is associated with the named semaphore. Output: semaphoreHandle: A handle to the semaphore. openCount: The current number of processes that have this semaphore open. Returns: Result code (see Appendix I) Netware C Library Chapter Ten - Synchronisation Services Page: 10-3 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 10.2.4 SignalSemaphore This increments the value of the specified semaphore. int SignalSemaphore( long semaphoreHandle ); Input: semaphoreHandle: Handle returned from the call to OpenSemaphore. Returns: Result code (see Appendix I) 10.2.5 WaitOnSemaphore This decrements the semaphore value. If the value becomes negative then the call will wait for the specified length of time. int WaitOnSemaphore( long semaphoreHandle , int timeoutLimit ); Input: semaphoreHandle: Handle returned from the call to OpenSemaphore. timeoutLimit: The length of time the process must wait if the semaphore is not available. This is in units of 1/18th of a second, 0 equals no wait. Returns: Result code (see Appendix I) Netware C Library Chapter Eleven - Communication Services Page: 11-1 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 11. Communication Services These services allow applications to use the Netware Internetwork Packet Exchange (IPX) and the Netware Sequenced Packet Exchange (SPX) protocols. These protocols are based on the Xerox Network Systems (XNS) Internet Transport Protocols. Both IPX and SPX allow peer-to-peer communication. This means that all communication is done directly between two or more workstations on the internet, bypassing the file server. Because nodes on an internet can communicate in various ways, the International Standards Organisation (ISO) proposed a standard model called the Open Systems Interconnection (OSI) model. The OSI model basically consists of seven layers, which are: Physical, Data Link, Network, Transport, Session, Presentation and Application. Each layer provides services to the next higher layer. The IPX protocol maps onto layer three (Network), which is concerned with packet addressing and routing, and the SPX protocol maps onto layer four (Transport), which is concerned with the guaranteed and sequenced delivery of packets. 11.1 IPX Protocol IPX is known as a connectionless or datagram protocol, this means that when IPX is used to communicate between two nodes on the network, no connection is established. Therefore there is no guarantee that data sent from one node will be received by the destination node. There are two structures that are needed in order to use IPX, these are the IPX packet and the Event Control Block (ECB). For every IPX packet there is an associated ECB. 11.1.1 IPX Packet Structure An IPX packet consists of a 30-byte header plus any number of data fragments as long as the total length of the packet does not exceed 576 bytes. IPX does not use the data fragments, and so these can be application defined, but the header, as defined in the file "ipxspx.h", is as follows: typedef struct { byte network_number[4]; byte node_address[6]; nw_int socket_number; } NETWORK_ADDR; typedef struct { nw_int checksum; nw_int length; byte transport_control; byte packet_type; NETWORK_ADDR dest_addr; NETWORK_ADDR srce_addr; } IPX_HEADER; All the fields with the exception of "packet_type" and "dest_addr" are set automatically by IPX. Netware C Library Chapter Eleven - Communication Services Page: 11-2 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ For IPX "packet_type" should be set to either 0 or 4, but it can take the following values: 0 Unknown packet type 1 Routing information packet 2 Echo packet 3 Error packet 4 Packet exchange packet 5 Sequenced packet protocol packet 16 Experimental protocol 17 Netware core protocol 18-31 Experimental protocols The "dest_addr" field contains the network number and node address of the destination node, along with the socket number that the destination is listening on for this communication, see the definition of the function IPX_OPEN_SOCKET for more information about sockets. 11.2 SPX Protocol SPX is known as a connection-oriented protocol, this means that before a packet can be sent a connection must be established between the source and destination nodes. SPX automatically performs the tasks of guaranteeing delivery of packets, sequencing of packets and the detection and correction of errors. Like IPX there are two structures that are needed in order to use SPX, these are the SPX packet and the Event Control Block (ECB). For every SPX packet there is an associated ECB. 11.2.1 SPX Packet Structure An SPX packet consists of a 42-byte header plus any number of data fragments as long as the total length of the packet does not exceed 576 bytes. SPX does not use the data fragments, and so these can be application defined, but the header, as defined in the file "ipxspx.h", is as follows: typedef struct { IPX_HEADER ipx; byte connection_control; byte datastream_type; nw_int source_connection_id; nw_int dest_connection_id; nw_int sequence_number; nw_int acknowledge_number; nw_int allocation_number; } SPX_HEADER; The first 30 bytes have the same meaning as the IPX header, except that the packet type field must be set to 5 to signify that it is an SPX packet. The additional fields for SPX are defined as follows: connection_control: This field contains four flags that are used by SPX to control the flow of data across the connection: Netware C Library Chapter Eleven - Communication Services Page: 11-3 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Bits 7 6 5 4 3 2 1 0 - - - x - - - - End-of-Message - - x - - - - - Attention - x - - - - - - Acknowledgement-Required x - - - - - - - System-Packet End-of-Message: This flag is set to signal an end of connection. SPX ignores this bit and passes it on unchanged to the destination. Attention: This flag is set if the packet is an attention packet. SPX ignores this bit and passes it on unchanged to the destination. Acknowledgement-Required: This bit is set by SPX if an acknowledgement packet is required. SPX handles acknowledgement requests and responses automatically. System-Packet: SPX sets this bit if the packet is a system packet. These packets are used internally by SPX. datastream_type: This indicates the type of data that can be found in the packet. It can take the following values: 0 to 253 User defined ( SPX ignores these values ). 254 End-of-Connection. This packet type is generated by SPX when an SPXTerminateConnection call is issued. 255 End-of-Connection-Acknowledgement. This is sent by SPX whenever a workstation receives an End-of-Connection packet. source_connection_id: SPX sets this field to the SPX connection id of the source workstation. dest_connection_id: SPX sets this field to the SPX connection id of the destination workstation. sequence_number: SPX uses this field to identify and discard duplicate packets. It is set and maintained by SPX. Netware C Library Chapter Eleven - Communication Services Page: 11-4 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ acknowledge_number: SPX uses this field to indicate the sequence number of the next packet SPX expects to receive. allocation_number: This is used internally by SPX, it contains the number of packets sent but not yet acknowledged by the destination workstation. 11.3 Event Control Block (ECB) This is a structure that contains details about the IPX/SPX packet, particularly the number of fragments and the size and address of each one. For a send ECB, IPX will collect together all the fragments that are specified in the ECB into one buffer before transmitting the packet, and for a receive ECB, IPX will distribute the received packet into the appropriate addresses specified by the ECB. The ECB also contains the completion code of the send or receive process. 11.3.1 ECB Structure The ECB structure declared in "ipxspx.h" contains only two fragments, the first is for the IPX/SPX header and the second is for the users data. The structure definition is as follows: typedef struct { void _far *address; word length; } ECB_FRAGMENT; typedef struct { void _far *link_address; void (_far *esr)(void); byte in_use; byte completion_code; nw_int socket_number; byte IPX_workspace[4]; byte driver_workspace[12]; byte immediate_address[6]; word fragment_count; ECB_FRAGMENT fragment[2]; } EVENT_CONTROL_BLOCK; link_address: This is maintained by IPX whilst the ECB is in use. When the ECB is not in use then the application can use this field. esr: This contains the address of an application defined Event Service Routine (ESR) that IPX will call when the send or receive event finishes. IPX also maintains the in_use and completion_code fields, so an application could simply poll these fields instead of using an ESR. If no ESR is required then this field should be set to a null pointer. Netware C Library Chapter Eleven - Communication Services Page: 11-5 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ in_use: Whilst the ECB is in use, this field will contain a non-zero value. Once IPX has finished with the ECB, i.e. the send or receive has finished, then this value will be set to zero. completion_code: This field is set by IPX to indicate the result of the send or receive event. This field is undefined whilst the in_use flag is non-zero. The following completion codes can be reported: Send-ECB: 0x00 Successful - The request was sent 0xfc Cancelled - The send request was cancelled 0xfd Malformed - The packet was malformed 0xfe Undelivered - The packet could not be delivered 0xff Hardware Failure - There has been a physical hardware or network failure. Listen-ECB: 0x00 Successful - A packet was received 0xfc Cancelled - The listen request was cancelled 0xfd Overflow - A packet was received, but the fragment count in the ECB is zero, or the available space specified in the ECB is not large enough to hold the entire packet. 0xff Closed - The listening socket is not open. Timer-ECB: 0x00 Successful 0xfc Cancelled - The timer event was cancelled. socket_number: This contains the number of the previously opened socket that is to be associated with this ECB. This is held in high-low format, so must be stored using the function NWintconvert, see section 1.7. IPX_workspace: This is reserved for use by IPX. driver_workspace: This is reserved for use by the network driver. immediate_address: This contains the address of the node to which the packet is to be sent or from which it was received. If the node is not on the local network then this will contain the address of an internetwork bridge. fragment_count: This contains the number of data fragments that are associated with this ECB. Netware C Library Chapter Eleven - Communication Services Page: 11-6 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ fragment.address: This contains the address of this fragment. fragment.length: This contains the length of this fragment. Netware C Library Chapter Eleven - Communication Services Page: 11-7 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 11.4 IPX Functions The following function calls use two structures that are declared in the header file "ipxspx.h". These are: typedef struct { byte network_number[4]; byte node_address[6]; } INTER_NETWORK_ADDR; typedef struct { INTER_NETWORK_ADDR ina; nw_int socket_number; } NETWORK_ADDR; 11.4.1 IPXCancelEvent This cancels an IPX/SPX event that is associated with a particular ECB. A completion code will be returned in the cancelled ECB, but the ESR wil not be actioned. word IPXCancelEvent( EVENT_CONTROL_BLOCK *ecb ); Input: ecb: Address of the ECB that is to be cancelled. Returns: Result code (see Appendix I) 11.4.2 IPXCloseSocket This closes a socket that was previously opened by IPXOpenSocket. Any events that are associated with the socket will be cancelled. void IPXCloseSocket( word socketNumber ); Input: socketNumber: Number of the socket to close. 11.4.3 IPXDisconnectFromTarget An application uses this function to notify a listening node that no more IPX packets are going to be sent. void IPXDisconnectFromTarget( NETWORK_ADDR *networkAddress ); Input: networkAddress: Full network address of the node with which the connection is being terminated. Netware C Library Chapter Eleven - Communication Services Page: 11-8 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 11.4.4 IPXGetInternetworkAddress This returns the network number and node address of the calling workstation. void IPXGetInternetworkAddress(INTER_NETWORK_ADDR *networkAddress); Output: networkAddress: Network number and node address of the calling workstation. 11.4.5 IPXGetIntervalMarker This returns the number of clock ticks that have occured in the requesting workstation since IPX was loaded. Approximately 18.2 clock ticks occur every second. word IPXGetIntervalMarker( void ); Returns: The number of clock ticks since IPX was loaded. 11.4.6 IPXGetLocalTarget This returns the information that is required for the immediate_address field in an IPXSendPacket ECB. The returned node address is either the address of the nearest bridge, if the packet must cross a bridge, or the address of the destination workstation. word IPXGetLocalTarget( INTER_NETWORK_ADDR *networkAddress , byte *immediateAddress, word *transportTime ); Input: networkAddress: The network number and node address of the destination workstation. Output: immediateAddress: The routing address of the destination. This must be placed in the immediate_address field of a send ECB. transportTime: This is the number of timer ticks that a packet will take in order to get to the destination. Returns: Result code (see Appendix I) 11.4.7 IPXInitialise This initialises the areas used by the IPX library functions. It must be the first IPX function that is called. word IPXInitialise( void ); Returns: 0 IPX is installed -1 IPX is not installed Netware C Library Chapter Eleven - Communication Services Page: 11-9 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 11.4.8 IPXListenForPacket One or more calls to this function must be made in order to give IPX the address of a buffer in which the next incoming message packet must be placed. Each call gives IPX an ECB that is then placed in a pool of listening ECBs. An immediate return to the calling program is made after each call. When IPX receives a packet one of the listening ECBs that has a matching socket number is selected. The ECBs are selected in a random order. word IPXListenForPacket( EVENT_CONTROL_BLOCK *ecb ); Input: ecb: Address of the listening ECB. Returns: Result code (see Appendix I) 11.4.9 IPXOpenSocket This function opens a socket that can then be used by either IPX or SPX, but not by both simultaneously. word IPXOpenSocket( word *socketNumber, byte longevity ); Input: socketNumber: The number of the socket to open. A value of zero will cause IPX to generate a socket number in the range 0x4000 to 0x8000. Socket numbers in the range 0x0000 to 0x0bb9 and 0x8001 to 0xffff are reserved and must not be used. longevity: This specifies whether the socket is short-lived (0x00) or long-lived (0xff). A short-lived socket is closed automatically when the application terminates or when a call to IPXCloseSocket is made, long-lived sockets must be closed explicitly by calling IPXCloseSocket. Output: socketNumber: Returns the actual socket number that was opened. Returns: Result code (see Appendix I) 11.4.10 IPXRelinquishControl This must be called at periodic intervals in order to give IPX time to process events. void IPXRelinquishControl( void ); Netware C Library Chapter Eleven - Communication Services Page: 11-10 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 11.4.11 IPXScheduleIPXEvent This function passes an ECB to IPX for processing at a later time. IPX returns to the application immediately after this call and waits in the background until the delay period has expired. void IPXScheduleIPXEvent( EVENT_CONTROL_BLOCK *ecb , word delayTicks ); Input: ecb: Address of the ECB to be processed. delayTicks: Number of clock ticks that IPX must wait for before processing the ECB. Approximately 18.2 clock ticks occur every second. 11.4.12 IPXSendPacket This function instructs IPX to send a data packet. void IPXSendPacket( EVENT_CONTROL_BLOCK *ecb ); Input: ecb: Address of the ECB containing the routing information and the data that is to be used in constructing the packet. Netware C Library Chapter Eleven - Communication Services Page: 11-11 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 11.5 SPX Functions 11.5.1 SPXAbortConnection This function aborts an SPX connection by abnormally terminating any outstanding SPX events. No notification of the termination is sent to the other station. void SPXAbortConnection( word connectionID ); Input: connectionID: SPX connection id of the connection to be broken. 11.5.2 SPXEstablishConnection This function creates a connection between the calling station and the specified destination station. The destination station must have issued an SPXListenForConnection. Before issuing this call, the application must have created at least two listen ECBs and passed them to SPX by calling the function SPXListenForSequencedPacket. Once the establish connection packet has been sent, then SPX will use one of the listen ECBs to receive an acknowledgement packet from the destination station. word SPXEstablishConnection( word retryCount, word watchdogFlag , EVENT_CONTROL_BLOCK *ecb ,word *connectionID ); Input: retryCount: This specifies how many times SPX will resend an unacknowledged packet before giving up. A value of zero indicates that SPX should use its internal default value. watchdogFlag: This can have the value of 0 (watchdog disabled) or 1 (watchdog enabled). If watchdog is enabled then the SPX watchdog process will monitor the SPX connection to ensure that it is functioning. If watchdog process determines that a connection has failed, then it will use one of the outstanding listen ECBs to report the failure. ecb: Address of the ECB containing the information that is required in order to establish the connection. The socket number, fragment count and fragment descriptor fields in the ECB must be setup. The fragment count field must be 1, and the fragment descriptor field msut point to a 42-byte SPX packet header. The SPX packet header's destination network node and socket number must be initialised to their relevant values. Output: connectionID: The returned SPX connection id. Returns: Result code (see Appendix I) Netware C Library Chapter Eleven - Communication Services Page: 11-12 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 11.5.3 SPXGetConnectionStatus This function returns the status of the specified SPX connection. word SPXGetConnectionStatus( word connectionID , SPX_CONNECTION_STATUS *connectionStatus ); Input: connectionID: SPX connection id. Output: connectionStatus: Structure containing the status of the SPX connection. It is declared in the header file "ipxspx.h". See Appendix III. Returns: Result code (see Appendix I) 11.5.4 SPXInitialise This function determines whether SPX is installed. int SPXInitialise(byte *majorVersion,byte *minorVersion, word *maxConnections,word *availableConnections ); Output: majorVersion: Major revision number of SPX. minorVersion: Minor revision number of SPX. maxConnections: Maximum number of SPX connections that are supported. availableConnections: The number of SPX connections that are available. Returns: 0 SPX is installed -1 SPX is not installed 11.5.5 SPXListenForConnection This function instructs SPX to expect a request from another station to establish a connection. SPX returns immediately to the caller, and waits for the request packet in background. void SPXListenForConnection( word retryCount, word watchdogFlag , EVENT_CONTROL_BLOCK *ecb ); Input: retryCount: This specifies how many times SPX will resend an unacknowledged packet before giving up. A value of zero indicates that SPX should use its internal default value. watchdogFlag: This can have the value of 0 (watchdog disabled) or 1 (watchdog enabled). If watchdog is enabled then the SPX watchdog process will monitor the SPX connection to ensure that it is functioning. If watchdog process determines that a connection has failed, then it will use one of the outstanding listen ECBs to report the failure. Netware C Library Chapter Eleven - Communication Services Page: 11-13 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ecb: Address of the ECB containing the information that is required in order to establish the connection. The socket number, fragment count and fragment descriptor fields in the ECB must be setup. The fragment count field must be 1, and the fragment descriptor field msut point to a 42-byte SPX packet header. When a connection is made, then SPX will return a connection ID in the first two bytes of the IPX_workspace field of the ECB associated with the SPXListenForConnection call, the driver_workspace field will also contain the address of the partner node. 11.5.6 SPXListenForSequencedPacket This function gives SPX an ECB and a packet buffer it can use when it receives an incoming data packet. SPX will place each ECB and buffer in a pool and will then return immediately to the caller. On receiving a data packet, SPX will select one of the available listening ECBs for the relevant socket number. void SPXListenForSequencedPacket( EVENT_CONTROL_BLOCK *ecb ); Input: ecb: Address of the listening ECB. The ecb should be initialised as follows: fragment_count = 2 fragment[0].address = Address of SPX header fragment[0].length = 42 fragment[1].address = Address of data buffer fragment[1].length = Length of data buffer Netware C Library Chapter Eleven - Communication Services Page: 11-14 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 11.5.7 SPXSendSequencedPacket This function instructs SPX to send a data packet to the other station associated with the connection. The actual send operation is performed in the background. void SPXSendSequencedPacket( word connectionID, EVENT_CONTROL_BLOCK *ecb ); Input: connectionID: SPX connection id. ecb: Address of the send ecb. The ecb should be initialised as follows: fragment_count = 2 fragment[0].address = Address of SPX header fragment[0].length = 42 fragment[1].address = Address of data buffer fragment[1].length = Length of data buffer 11.5.8 SPXTerminateConnection This function terminates an SPX connection. The termination operation is performed in the background. A termination packet will be sent to the partner station. void SPXTerminateConnection( word connectionID , EVENT_CONTROL_BLOCK *ecb ); Input: connectionID: SPX connection id. ecb: Address of the ecb. The ecb should be initialised as follows: fragment_count = 1 fragment[0].address = Address of SPX header fragment[0].length = 42 Netware C Library Appendix I - Netware Result Codes Page: A1-1 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÉÍÍÍÍÑÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍËÍÍÍÍÍÑÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ» ºHex ³Meaning º Hex ³Meaning º ÌÍÍÍÍØÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÎÍÍÍÍÍØÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ͹ º00h ³Action Successful º 9Ah ³Renaming Across Volumes º º ³Server Not In Use º 9Bh ³Bad Directory Handle º º ³TTS Not Available º 9Ch ³Invalid Path º º01h ³Server In Use º ³No more Trustees º º ³Semaphore Overflow º 9Dh ³No More Directory Handles º º ³TTS Available º 9Eh ³Invalid Filename º º02h ³DOS File Not Found º 9Fh ³Directory Active º º03h ³DOS Path Not Found º A0h ³Directory Not Empty º º04h ³DOS Too Many Open Files º A1h ³Directory IO Error º º05h ³DOS Access Denied º A2h ³Read File With Record Locked º º06h ³DOS Invalid File Handle º BBh ³No Netware shell loaded º º07h ³DOS Memory Blocks Destroyed º C0h ³No Account Privileges º º08h ³DOS Insufficient Memory º C1h ³Login Denied - º º09h ³DOS Invalid Memory Block Address º ³No Account Balance º º0Ah ³DOS Invalid Environment º C2h ³Account Credit limit Exceeded º º0Bh ³DOS Invalid Format º ³Login Denied - No credit º º0Ch ³DOS Invalid Access Code º C3h ³Account - Too many Holds º º0Dh ³DOS Invalid Data º C5h ³Intruder Detection Lock º º0Fh ³DOS Invalid Drive Specified º C6h ³Not Console Operator º º10h ³DOS Attempt To Delete Current Dirº D0h ³Queue Error º º11h ³DOS Not Same Device º D1h ³No Queue º º12h ³DOS No More Files º D2h ³No Queue Server º º20h ³DOS Sharing Violation º D3h ³No Queue Rights º º21h ³DOS Lock Violation º D4h ³Queue Full º º80h ³File In User Error º D5h ³No Queue Job º º81h ³No More File Handles º D6h ³No Job Rights º º82h ³No Open Privileges º D7h ³Password Not Unique º º83h ³IO Error Network Disk º ³Queue Servicing º º84h ³No Create Privileges º D8h ³Password Too Short º º85h ³No Delete Privileges º ³Queue Not Active º º86h ³Create File Exists Read Only º D9h ³Login Denied - No connection º º87h ³Wild Cards in Create File Name º ³Station Not Server º º88h ³Invalid File Handle º DAh ³Unauthorized login time - º º89h ³No Search Privileges º ³Queue Halted º º8Ah ³No Delete Privileges º DBh ³Unauthorized login station - º º8Bh ³No Rename Privileges º ³Max Queue Servers º º8Ch ³No Modify Privileges º DCh ³Account Disabled º º8Dh ³Some Files Affected In Use º DEh ³Password has expired - No Graceº º8Eh ³No Files Affected In Use º DFh ³Password has expired º º8Fh ³Some Files Affected Read Only º E8h ³Not Item Property - º º90h ³No Files Affected Read Only º ³Write Property to Group º º91h ³Some Files Renamed - Name Exists º E9h ³Member Already Exists º º92h ³No Files Renamed - Name Exists º EAh ³No Such Member º º93h ³No Read Privileges º EBh ³Not Group Property º º94h ³No Write Privileges or Read Only º ECh ³No Such Segment º º95h ³File Detached º EDh ³Property Already Exists º º96h ³Server Out Of Memory º EEh ³Object Already Exists º º ³Out Of Dynamic Workspace º EFh ³Invalid Name º º97h ³No Disk Space for Spool File º F0h ³Wild Card Not Allowed º º98h ³Volume Does Not Exist º F1h ³Invalid Bindery Security º º99h ³Directory Full º F2h ³No Object Read Privilege º ÈÍÍÍÍÏÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÊÍÍÍÍÍÏÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍͼ Netware C Library Appendix I - Netware Result Codes Page: A1-2 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÉÍÍÍÍÑÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍËÍÍÍÍÍÑÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ» ºHex ³Meaning º Hex ³Meaning º ÌÍÍÍÍØÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÎÍÍÍÍÍØÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ͹ ºF3h ³No Object Rename Privilege º FFh ³Bad Printer Error º ºF4h ³No Object Delete Privilege º ³Bad Record Offset º ºF5h ³No Object Create Privilege º ³Close FCB Error º ºF6h ³No Property Delete Privilege º ³File Extension Error º º ³Not Same Local Drive º ³File Name Error º ºF7h ³No Property Create Privilege º ³Hardware Failure º º ³Target Drive Not Local º ³Invalid Drive Number º ºF8h ³Already Attached To Server º ³Invalid Initial Semaphore Valueº º ³No Property Write Privilege º ³Invalid Semaphore Handle º º ³Not Attached To Server º ³IO Bound Error º ºF9h ³No Free Connection Slots º ³No Files Found Error º º ³No Property Read Privilege º ³No Response From Server º ºFAh ³No More Server Slots º ³No Such Object º º ³Temporary Remap Error º ³Bad Password º ºFBh ³Invalid Parameters º ³Path Not Locatable º º ³No Such Property º ³Queue Full Error º º ³Unknown Request º ³Request Not Outstanding º ºFCh ³Unknown File Server º ³Transaction Not Yet Written º º ³Message Queue Full º ³No More Matching Files º º ³No Such Object º ³Bindery Failure º ºFDh ³Bad Station Number º ³Explicit Transaction Active º º ³Unknown Request º ³No Explicit Transaction Active º º ³Field Already Locked º ³No Record Found º º ³TTS Disabled º ³ º ºFEh ³Bindery Locked º ³ º º ³Directory Locked º ³ º º ³Invalid Semaphore Name Length º ³ º º ³Server Bindery Locked º ³ º º ³Spool Directory Error º ³ º º ³Supervisor has disabled login º ³ º º ³Timeout Failure º ³ º º ³Transaction ends Record Lock º ³ º º ³Implicit Transaction Active º ³ º ÈÍÍÍÍÏÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÊÍÍÍÍÍÏÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍͼ Netware C Library Appendix II - Function List Page: A2-1 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ AddBinderyObjectToSet Bindery Services 2.3.1 AddTrusteeToDirectory Directory Services 8.6.1 AllocPermanentDirectoryHandle Directory Services 8.6.2 AllocTemporaryDirectoryHandle Directory Services 8.6.3 AttachToFileServer Connection Services 4.1.1 BroadcastToConsole Message Services 6.1.1 CancelLPTCapture Print Services 9.1.1 CancelSpecificLPTCapture Print Services 9.1.2 ChangeBinderyObjectPassword Bindery Services 2.3.2 ChangeBinderyObjectSecurity Bindery Services 2.3.3 ChangePropertySecurity Bindery Services 2.3.4 CheckConsolePrivileges File Server Services 3.1.1 CheckPipeStatus Message Services 6.1.2 ClearConnectionNumber File Server Services 3.1.2 CloseBindery Bindery Services 2.3.5 CloseMessagePipe Message Services 6.1.3 CloseSemaphore Synchronisation Services 10.2.1 CreateBinderyObject Bindery Services 2.3.6 CreateDirectory Directory Services 8.6.4 CreateProperty Bindery Services 2.3.7 DeallocateDirectoryHandle Directory Services 8.6.5 DeleteBinderyObject Bindery Services 2.3.9 DeleteBinderyObjectFromSet Bindery Services 2.3.8 DeleteDirectory Directory Services 8.6.6 DeleteFakeRoot Directory Services 8.6.7 DeleteProperty Bindery Services 2.3.10 DeleteTrusteeFromDirectory Directory Services 8.6.8 DetachFromFileServer Connection Services 4.1.2 DisableFileServerLogin File Server Services 3.1.3 DisableTransactionTracking File Server Services 3.1.4 DownFileServer File Server Services 3.1.5 EnableFileServerLogin File Server Services 3.1.6 EnableTransactionTracking File Server Services 3.1.7 EncryptPassword File Server Services 3.1.8 EndLPTCapture Print Services 9.1.3 EndOfJob Workstation Services 5.2.1 EndSpecificLPTCapture Print Services 9.1.4 EnterLoginArea Connection Services 4.1.3 EraseFiles File Services 7.5.1 ExamineSemaphore Synchronisation Services 10.2.2 FlushLPTCapture Print Services 9.1.5 FlushSpecificLPTCapture Print Services 9.1.6 GetBannerUserName Print Services 9.1.7 GetBinderyAccessLevel Bindery Services 2.3.11 GetBinderyObjectDiskSpaceLeft File Server Services 3.1.9 GetBinderyObjectID Bindery Services 2.3.12 GetBinderyObjectName Bindery Services 2.3.13 GetBroadcastMessage Message Services 6.1.4 GetBroadcastMode Message Services 6.1.5 GetConnectionIDTable Workstation Services 5.2.2 GetConnectionInformation Connection Services 4.1.4 GetConnectionNumber Connection Services 4.1.5 GetConnectionsOpenFiles File Server Services 3.1.10 GetConnectionsUsageStatistics File Server Services 3.1.11 GetCurrentDirectory Directory Services 8.6.9 GetDefaultCaptureFlags Print Services 9.1.10 Netware C Library Appendix II - Function List Page: A2-2 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ GetDefaultConnectionID Workstation Services 5.2.3 GetDefaultLocalPrinter Print Services 9.1.9 GetDirectoryHandle Directory Services 8.6.10 GetDirectoryPath Directory Services 8.6.11 GetDiskCacheStatistics File Server Services 3.1.12 GetDiskUtilisation File Server Services 3.1.13 GetDriveConnectionID Workstation Services 5.2.4 GetDriveFlagTable Workstation Services 5.2.5 GetDriveHandleTable Workstation Services 5.2.6 GetEffectiveDirectoryRights Directory Services 8.6.12 GetFileServerDateTime File Server Services 3.1.14 GetFileServerInformation File Server Services 3.1.15 GetFileServerLoginStatus File Server Services 3.1.16 GetFileServerTable Workstation Services 5.2.7 GetInternetAddress Connection Services 4.1.6 GetLPTCaptureStatus Print Services 9.1.8 GetNetwareShellVersion Workstation Services 5.2.8 GetNetworkSerialNumber File Server Services 3.1.17 GetNumberOfLocalDrives Workstation Services 5.2.9 GetObjectConnectionNumbers Connection Services 4.1.7 GetPathFromDirectoryEntry File Server Services 3.1.18 GetPersonalMessage Message Services 6.1.6 GetPhysicalDiskStatistics File Server Services 3.1.19 GetPreferredConnectionID Workstation Services 5.2.10 GetPrimaryConnectionID Workstation Services 5.2.11 GetPrinterStatus Print Services 9.1.11 GetSemaphoreInformation File Server Services 3.1.20 GetServerConnectionID Workstation Services 5.2.12 GetSpecificCaptureFlags Print Services 9.1.12 GetStationAddress Connection Services 4.1.8 GetVolumeInformation Directory Services 8.6.13 GetVolumeInfoWithHandle Directory Services 8.6.14 GetVolumeInfoWithNumber Directory Services 8.6.15 GetVolumeName Directory Services 8.6.16 GetVolumeNumber Directory Services 8.6.17 IsShellLoaded Workstation Services 5.2.13 IPXCancelEvent Communication Services 11.4.1 IPXCloseSocket Communication Services 11.4.2 IPXDisconnectFromTarget Communication Services 11.4.3 IPXGetInternetworkAddress Communication Services 11.4.4 IPXGetIntervalMarker Communication Services 11.4.5 IPXGetLocalTarget Communication Services 11.4.6 IPXInitialise Communication Services 11.4.7 IPXListenForPacket Communication Services 11.4.8 IPXOpenSocket Communication Services 11.4.9 IPXRelinquishControl Communication Services 11.4.10 IPXScheduleIPXEvent Communication Services 11.4.11 IPXSendPacket Communication Services 11.4.12 IsBinderyObjectInSet Bindery Services 2.3.14 LoginObjectEncrypted Connection Services 4.1.9 LoginToFileServer Connection Services 4.1.10 LogNetworkMessage Message Services 6.1.7 Logout Connection Services 4.1.12 LogoutFromFileServer Connection Services 4.1.11 MapFakeRoot Directory Services 8.6.18 ModifyMaximumRightsMask Directory Services 8.6.19 Netware C Library Appendix II - Function List Page: A2-3 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ OpenBindery Bindery Services 2.3.15 OpenMessagePipe Message Services 6.1.8 OpenSemaphore Synchronisation Services 10.2.3 PurgeAllErasedFiles File Services 7.5.2 PurgeErasedFiles File Services 7.5.3 ReadPropertyValue Bindery Services 2.3.16 RenameBinderyObject Bindery Services 2.3.17 RenameDirectory Directory Services 8.6.20 RestoreDirectoryHandle Directory Services 8.6.21 SaveDirectoryHandle Directory Services 8.6.22 ScanBinderyObject Bindery Services 2.3.18 ScanBinderyObjectTrusteePaths Directory Services 8.6.23 ScanDirectoryForTrustees Directory Services 8.6.24 ScanDirectoryInformation Directory Services 8.6.25 ScanFileInformation File Services 7.5.4 ScanProperty Bindery Services 2.3.19 SendBroadcastMessage Message Services 6.1.9 SendConsoleBroadcast File Server Services 3.1.21 SendPersonalMessage Message Services 6.1.10 SetBannerUserName Print Services 9.1.13 SetBroadcastMode Message Services 6.1.11 SetCapturePrintQueue Print Services 9.1.14 SetDefaultCaptureFlags Print Services 9.1.16 SetDefaultLocalPrinter Print Services 9.1.15 SetDirectoryHandle Directory Services 8.6.26 SetEndofJobStatus Workstation Services 5.2.14 SetNWErrorMode Workstation Services 5.2.15 SetPreferredConnectionID Workstation Services 5.2.16 SetPrimaryConnectionID Workstation Services 5.2.17 SetSpecificCaptureFlags Print Services 9.1.17 SignalSemaphore Synchronisation Services 10.2.4 SpecifyCaptureFile Print Services 9.1.18 SPXAbortConnection Communication Services 11.5.1 SPXEstablishConnection Communication Services 11.5.2 SPXGetConnectionStatus Communication Services 11.5.3 SPXInitialise Communication Services 11.5.4 SPXListenForConnection Communication Services 11.5.5 SPXListenForSequencedPacket Communication Services 11.5.6 SPXSendSequencedPacket Communication Services 11.5.7 SPXTerminateConnection Communication Services 11.5.8 StartLPTCapture Print Services 9.1.19 StartSpecificLPTCapture Print Services 9.1.20 VerifyBinderyObjectPassword Bindery Services 2.3.20 VerifyObjectPasswordEncrypted Bindery Services 2.3.21 WaitOnSemaphore Synchronisation Services 10.2.5 WritePropertyValue Bindery Services 2.3.22 Netware C Library Appendix III - Data Structures Page: A3-1 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ These are the structures that are used by some of the Netware calls. Elements within them that have types nw_long or nw_int must be converted using convertNWlong or convertNWint respectively. All the structures are declared in the header files provided with the libraries. A3.1 CONNECTION_ID_TABLE This is used by GetConnectionIDTable in the Workstation Services. typedef struct { byte slot_in_use; byte servers_order_number; byte servers_network_number[4]; byte physical_node_address[6]; nw_int socket_number; word receive_timeout; byte routers_physical_node_address[6]; byte packet_sequence_number; byte connection_number; byte connection_status; word maximum_time_out; word connection_word; byte major_server_version; byte server_flags; byte minor_server_version; } CONNECTION_ID_TABLE; slot_in_use: A zero value indicates that this slot is not in use, possible non-zero values are: 0xe0 = AES Temporary Indicator 0xf8 = IPX in critical process 0xfa = Processing 0xfb = Holding (in processing after an event occurred) 0xfc = AES Waiting 0xfd = Waiting 0xfe = Receiving 0xff = Sending servers_order_number: This is the order number assigned to the corresponding server. The server with the lowest network/node address has the lowest order number. This will be a value 1 - 8. servers_network_number: This identifies the network which the file server is attached. If the server is attached to more than one LAN then this will always be for the servers LAN A. physical_node_address: This is the address of the servers LAN board. socket_number: The socket the shell uses for communicating with the server. receive_timeout: How long the shell should wait before resending an unanswered request. This is adjusted dynamically by the shell, but will never exceed the value in maximum_time_out. routers_physical_node_address: This is the address of the preferred bridge to route requests through, if it is not a Netware C Library Appendix III - Data Structures Page: A3-2 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ direct connection. packet_sequence_number: This is used as a packet ID to check that the reply received is answering the last request. connection_number: This corresponds to the entry in the file servers connection table. 0xff = No Connection. connection_status: This is the status of the connection. 0x00 = Connection functioning maximum_time_out: This is the maximum length of time that the shell should wait before resending an unanswered request. connection_word: 2-byte connection number, use this instead of connection_number. major_server_version: Major version number, less 2, of the corresponding server. server_flags: Low order bit will be set if burst mode is enabled. minor_server_version: Minor version number of the corresponding server. Netware C Library Appendix III - Data Structures Page: A3-3 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ A3.2 DISK_CACHE_STATISTICS This is used by GetDiskCacheStatistics in the File Server Environment Services. typedef struct { word buffer_length; nw_long system_elapsed_time; nw_int cache_buffer_count; nw_int cache_buffer_size; nw_int dirty_cache_buffers; nw_long cache_read_requests; nw_long cache_write_requests; nw_long cache_hits; nw_long cache_misses; nw_long physical_read_requests; nw_long physical_write_requests; nw_int physical_read_errors; nw_int physical_write_errors; nw_long cache_get_requests; nw_long cache_full_write_requests; nw_long cache_partial_write_requests; nw_long background_dirty_writes; nw_long background_aged_writes; nw_long total_cache_writes; nw_long cache_allocations; nw_int thrashing_count; nw_int LRU_block_was_dirty; nw_int read_beyond_write; nw_int fragmented_write_occurred; nw_int cache_hit_unavail_block; nw_int cache_block_scrapped; } DISK_CACHE_STATISTICS; buffer_length: Length of structure - 2 system_elapsed_time: This is the number of clock ticks, since the server was loaded. Each clock tick = 1/18th second approx. When this reaches 0xffffffff it wraps back to zero. cache_buffer_count: The number of cache buffers in the server. cache_buffer_size: Number of bytes in a cache buffer. dirty_cache_buffers: Number of buffers containing data that has not yet been written to disk. cache_read_requests: Number of times the cache software was asked to read some data. cache_write_requests: Number of times the cache software was asked to write some data. cache_hits: Number of times cache requests were available in existing cache blocks. cache_misses: Number of times cache requests were not available in cache blocks. physical_read_requests: Number of actual reads on the disk the cache software actioned. physical_write_requests: Number of actual writes to the disk the cache software actioned. physical_read_errors: Number of errors the cache software received whilst reading from the disk. physical_write_errors: Number of errors the cache software received Netware C Library Appendix III - Data Structures Page: A3-4 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ whilst writing to the disk. cache_get_requests: The number of times the cache software was asked to read information from the disk. cache_full_write_requests: The number of times the cache software was told to write information that exactly filled one or more sectors. cache_partial_write_requests: The number of times the cache software was told to write information that didn't exactly fill one or more sectors, this requires a disk pre-read. background_dirty_writes: The number of times that a whole cache block was completely written to a disk. background_aged_writes: Number of times a partially filled cache block was written to a disk, because it had not been accessed for a period of time. total_cache_writes: Total number of cache buffers written to disk. cache_allocations: Number of times a cache block was allocated for use. thrashing_count: Number of times a cache block was not available when a block allocation was requested. LRU_block_was_dirty: Number of times the least recently used (LRU) cache block algorithm reclaimed a dirty cache block. read_beyond_write: Number of times a file read request was made when file writes had not yet filled the cache block. fragmented_write_occurred: Number of dirty cache blocks that contained non-contiguous sectors of information were written, and the skipped sectors were not pre-read from the disk, this requires multiple disk writes. cache_hit_unavail_block: Number of cache requests that could be serviced from an available cache block, but the cache buffer could not be used, because it was in the process of being written to or read from the disk. cache_block_scrapped: The number of times a cache blocked is scrapped. This is due to the process going to sleep whilst it is waiting for a spare cache block, but when it wakes the data it was requesting has been read into another cache block by another process. This process has to then scrap the cache block it was waiting for and use the block that already contains the data. Netware C Library Appendix III - Data Structures Page: A3-5 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ A3.3 FILE_SERVER_INFO This is used by GetFileServerInformation in the File Server Environment Services. typedef struct { char server_name[48]; byte netware_version; byte netware_subversion; nw_int connections_supported; nw_int connections_in_use; nw_int max_connected_volumes; byte os_revision; byte SFT_level; byte TTS_level; nw_int peak_connections_used; byte accounting_version; byte VAP_version; byte queuing_version; byte print_server_version; byte virtual_console_version; byte security_restrictions_level; byte internet_bridge_version; byte reserved[60]; } FILE_SERVER_INFO; server_name[48]: 48-byte null terminated name of the server. netware_version: Version of Netware (1-255). netware_subversion: Sub-version of Netware (0-99). connections_supported: Number of connections supported. connections_in_use: Number of connections currently in use. max_connected_volumes: Maximum number of volumes on the server. os_revision: The revision number of the Operating System. SFT_level: System Fault Tolerance level. TTS_level: Transaction Tracking System level. peak_connections_used: Maximum number of connections that have been made since the server was loaded. accounting_version: The accounting version that is being used. VAP_version: The Value Added Process version number. queuing_version: The Queuing version number. print_server_version: The Print Server version number. virtual_console_version: The Virtual Console version number. security_restrictions_level: The security restrictions level. internet_bridge_version: The Internetwork Bridge version number. reserved[60]: Currently undefined. Netware C Library Appendix III - Data Structures Page: A3-6 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ A3.4 PHYSICAL_DISK_STATISTICS This is used by GetPhysicalDiskStatistics in the File Server Environment Services. typedef struct { word buffer_length; nw_long system_elapsed_time; byte physical_disk_channel; byte drive_removable_flag; byte physical_drive_type; byte controller_drive_number; byte controller_number; byte controller_type; nw_long drive_size; nw_int drive_cylinders; byte drive_heads; byte sectors_per_track; char drive_definition_string[64]; nw_int io_error_count; nw_long hot_fix_table_start; nw_int hot_fix_table_size; nw_int hot_fix_blocks_available; byte hot_fix_disabled; } PHYSICAL_DISK_STATISTICS; buffer_length: Length of structure - 2. system_elapsed_time: This is the number of clock ticks, since the server was loaded. Each clock tick = 1/18th second approx. When this reaches 0xffffffff it wraps back to zero. physical_disk_channel: The disk channel the disk is attached to. drive_removable_flag: A non-zero value indicates this drive is removable. physical_drive_type: The type of drive: 1=XT, 2=AT, 3=SCSI, 4=disk coprocessor, 5=PS/2 MFM controller, 6=PS/2 ESDI controller, 7=Convergent Technology SBIC, 50 to 255=Value-added disk drive. controller_drive_number: Drive number of the disk relative to the controller number. controller_number: The address on the physical disk channel of the disk's controller. controller_type: Contains a number indicating the type, make and model of the controller. drive_size: Size of the disk in blocks, 1 block = 4096 bytes. This does not include the area of the disk reserved for Hot Fix. drive_cylinders: Number of cylinders on the drive. drive_heads: Number of heads on the drive. sectors_per_track: The number of sectors on each track. 1 sector = 512 bytes. drive_definition_string: 64-byte null terminated string holding the make and model of the drive. io_error_count: This is the number of I/O errors on the disk since the server was loaded. Netware C Library Appendix III - Data Structures Page: A3-7 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ hot_fix_table_start: This is the first block of the Hot Fix area on the disk. hot_fix_table_size: Number of blocks in the Hot Fix area. hot_fix_blocks_available: Number of unused blocks in the Hot Fix area. hot_fix_disabled: A non-zero value indicates that Hot Fix redirection is disabled. Netware C Library Appendix III - Data Structures Page: A3-8 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ A3.5 PRINT_CONTROL_DATA This is used by the Print Services: GetDefaultCaptureFlags, GetSpecificCaptureFlags, SetDefaultCaptureFlags, SetSpecificCaptureFlags. typedef struct { byte Status; byte PrintFlags; byte TabSize; byte ServerPrinter; byte NumberCopies; byte FormType; byte Reserved1; byte BannerText[13]; byte Reserved2; byte LocalLPTDevice; nw_int FlushTimeoutCounter; byte FlushOnClose; nw_int MaximumLines; nw_int MaximumChars; byte FormName[13]; byte LPTFlag; byte FileFlag; byte TimeoutFlag; nw_long SetupBufferAddress; nw_long ResetBufferAddress; byte ConnectIdQPrintJob; byte InProgress; byte PrintQFlag; byte PrintJobValid; nw_long PrintQID; nw_int PrintJobNumber; } PRINT_CONTROL_DATA; Status: This is always set to 0x00 PrintFlags: This includes the following bits: (MSB) Bit 7: The banner page is printed 6: Tab size plus other print control sequences, will be interpreted by the server's print process. 5-4: Not specified 3: The server's print service will suppress the automatic form feed at the end of the print job 2: The print job is released for printing if the capture is broken by the connection to the server being lost. 1: Not specified (LSB) 0: Not specified TabSize: Current tab size (1-18) ServerPrinter: Printer number on which the captured file will be printed (0-4). Netware C Library Appendix III - Data Structures Page: A3-9 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ NumberCopies: Number of copies to print (0-255) FormType: The type of form that must be mounted in the printer for this file to be printed (0-255). Reserved1: Undefined BannerText[13]: 13-byte string that will be printed on the bottom half of a banner page. If this is null then the capture file name will be printed. Reserved2: Undefined LocalLPTDevice: The default LPT device (0-2,0=LPT1) FlushTimeoutCounter: This starts counting down every time an INT 17h is executed. When the timeout expires the capture file is flushed (0-65535). FlushOnClose: If this is zero (enabled) then the server will flush the capture file when the program ends the capture of the default LPT device. A non-zero value indicates this is disabled. MaximumLines: The maximum lines per page. MaximumChars: The maximum characters per line. FormName[13]: The name of the form that must be mounted in the printer for this file to print. LPTFlag: This is set (0xff) when the capture of the default LPT device is started, and cleared (0x00) when it is ended. FileFlag: This is et (0xff) when a capture filename is specified, but cleared (0x00) when one has not been specified. TimeoutFlag: This is set (0xff) when the timeout counter is counting down, and cleared (0x00) when it isn't. SetupBufferAddress: This points to a buffer containing the printer setup string. The buffer size is stored in the first word. ResetBufferAddress: This points to a buffer containing the printer reset string. The buffer size is stored in the first word. ConnectIdQPrintJob: This is the connection ID of the server queuing the print job. InProgress: This is set (0xff) when the first character of the print job is sent to the default LPT device. It is cleared (0x00) when then capture is ended,flushed or cancelled. PrintQFlag: This is set (0xff) when the print queue job entry is placed in the print queue. It is cleared (0x00) when the capture is ended, or cancelled. PrintJobValid: This is set (0xff) whilst the capture file is open, and cleared (0x00) when the capture is ended, cancelled or flushed. PrintQID: This is the bindery object ID of the print queue on the target server. PrintJobNumber: This is the job number the Queue Management System assigns to a print queue job entry. Netware C Library Appendix III - Data Structures Page: A3-10 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ A3.6 VOLUME_STATISTICS This is used by GetVolumeInformation in the Directory Services. typedef struct { word buffer_length; nw_long system_elapsed_time; byte volume_number; byte logical_drive_number; nw_int sectors_per_block; nw_int starting_block; nw_int total_blocks; nw_int available_blocks; nw_int total_directory_slots; nw_int available_directory_slots; nw_int max_used_dir_entries; byte volume_is_hashed; byte volume_is_cached; byte volume_is_removable; byte volume_is_mounted; char volume_name[17]; } VOLUME_STATISTICS; buffer_length: Length of structure - 2 system_elapsed_time: This is the number of clock ticks, since the server was loaded. Each clock tick = 1/18th second approx. When this reaches 0xffffffff it wraps back to zero. volume_number: This identifies the volume in the servers Volume Table. logical_drive_number: This is the volumes logical drive number on the server. sectors_per_block: This is the number of 512-byte sectors held in each block. starting_block: The number of the first block of the volume. total_blocks: Total number of blocks on the volume. available_blocks: Total number of unused blocks on the volume. total_directory_slots: Total number of directory slots allocated for the volume at installation time. available_directory_slots: Total number of unused directory slots. max_used_dir_entries: Maximum directory slots used at any one time on the volume. volume_is_hashed: A non-zero value indicates that the volume is hashed in the servers memory. volume_is_cached: A non-zero value indicates that the volume is cached in the servers memory. volume_is_removable: A non-zero value indicates that the disk that holds the volume is removable. volume_is_mounted: A non-zero value indicates that the volume is mounted. volume_name[17]: The 17-byte null terminated volume name Netware C Library Appendix III - Data Structures Page: A3-11 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ A3.7 SPX_CONNECTION_STATUS This is used by SPXGetConnectionStatus in the Communication Services. typedef struct { byte connection_state; byte watchdog_is_on; nw_int local_connection_id; nw_int remote_connection_id; nw_int sequence_number; nw_int local_acknowledge_number; nw_int local_allocation_number; nw_int remote_acknowledge_number; nw_int remote_allocation_number; nw_int local_socket; byte immediate_address[6]; byte network_number[4]; byte node_address[6]; nw_int socket; nw_int retransmission_count; nw_int est_roundtrip_delay; nw_int retransmitted_packets; nw_int suppressed_packets; } SPX_CONNECTION_STATUS; connection_state: Current state of the connection. 0x01 Waiting. SPX is listening on the connection, waiting for an establish connection packet. 0x02 Starting. SPX is attempting to make a connection by sending establish connection packets. 0x03 Established. SPX has established a connection with a remote workstation. 0x04 Terminating. The remote work- station has terminated the connection. watchdog_is_on: If bit 1 is set, then the watchdog process is monitoring the connection. local_connection_id: The SPX connection id of this workstation. remote_connection_id: The SPX connection id of the remote station. sequence_number: The sequence number that the local SPX will assign to the next packet that it sends. This is incremented each time a packet is sent. When it reaches 0xffff it wraps back to zero. local_acknowledge_number: The sequence number of the next packet that the local SPX expects to receive. local_allocation_number: This is the number of outstanding listen ECBs that are available for the local SPX. The remote SPX is allowed to send packets with sequence numbers up to and including the local_allocation_number. This number is incremented as the local workstation generates listen ECBs. When this number reaches 0xffff it wraps back to zero. Netware C Library Appendix III - Data Structures Page: A3-12 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ remote_acknowledge_number: This is the sequence number of the next packet that the remote SPX expects to receive from the local SPX. remote_allocation_number: This is the number of outstanding listen ECBs that are available to the remote SPX. The local SPX is allowed to send packets with sequence numbers up to and including the remote_allocation_number. This number is incremented as the remote station generates listen ECBs. When this number reaches 0xffff it wraps back to zero. local_socket: This is the socket number that the local SPX is using to send and receive packets. immediate_address[6]: This is the address of the bridge that routes the packets to and from the remote station. If the loacl and remote stations are on the same local network, then this is the address of the remote station. network_number[4]: The network number that the remote station is on. node_address[6]: The node address of the remote station. socket: The socket number that the remote station is using to send and receive packets. retransmission_count: The number of times that SPX will attempt to resend an unacknowledged packet before it determines that the remote half of the connection is no longer responding. est_roundtrip_delay: This is the number of clock ticks that the local SPX will wait for before resending a packet. retransmitted_packets: The number of times that the local SPX has had to resend a packet for this connection. suppressed_packets: The number of packets that have been discarded by the local SPX, possibly due to a duplicate packet being received. Netware C Library Appendix IV - Order Form Page: A4-1 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Return to: Adrian Cunnelly 18 Kingsley Avenue, Heaton Norris, Stockport, Cheshire. SK4 1PW ENGLAND Name: __________________________________________________ Company: __________________________________________________ Address: __________________________________________________ __________________________________________________ __________________________________________________ __________________________________________________ Phone: __________________________________________________ Diskette size (Select one): [___] 5.25" 1.2mb [___] 5.25" 360k [___] 3.5" 1.44mb [___] 3.5" 720k Registration..................................œ10 œ____ ( inc. Large,Medium & Small memory models, for Microsoft C 6.0 , Turbo C 2.0 & Borland C++ 2.0 ) Registration + Source code....................œ40 œ____ Printed manual.........................[ ] @ œ10 each œ____ Total..................................................œ____ (UK Pounds) All the above prices include postage and packing. All funds must be in UK Pounds.